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This manual describes the programming features of the UNIX system. For 
more information on UNIX System V/386, see the available documentation 
listed in the UNIX System V/386 Product Overview /Documentation Roadmap, 

Not all commands, features, and facilities described in this manual are 
available in every UNIX system. Some of the features require additional utili- 
ties which may not exist on your system. 

This manual is divided into five sections, some containing subsections. 

1. Commands 

2. System Calls 

3. Subroutines: 

3C. C Programming Language Libraries 
3S. Standard I/O Library Routines 
3M. Mathematical Library Routines 
3N. Networking Support Utilities 
3X. Specialized Libraries 

4. File Formats 

5. Miscellaneous Facilities. 

Section 1 (Commands) describes commands that support C and other pro- 
gramming languages. 

Section 2 (System Calls) describes the services provided by the UNIX Sys- 
tem kernel, including the C language interface. 

Section 3 (Subroutines) describes available subroutines. Their binary ver- 
sions reside in various system libraries in the directories /lib and /usr/lib. 
See intro(3) for descriptions of these libraries and the files in which they are 
stored. 

Section 4 (File Formats) documents the structure of particular kinds of 
files; for example, the format of the output of the link editor is given in 
a.out(4:). Excluded are files used by only one command (for example, the 
assembler's intermediate files). In general, the C language structures 
corresponding to these formats can be found in the directories /usr/include 
and /usr/include/sys. 
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Section 5 (Miscellaneous Facilities) contains a variety of things. Included 
are descriptions of character sets, macro packages, etc. 

References with numbers other than those above mean that the utility is 
contained in the appropriate section of another manual. References with (1) or 
(IM) following the command mean that the utility is contained in this manual 
or the User's/System Administrator's Reference Manual Those followed by (7) 
are contained in the User's /System Administrator's Reference Manual 

Each section consists of a number of independent entries of a page or so. 
Entries within each section are alphabetized, with the exception of the intro- 
ductory entry that begins each section (also Section 3 is in alphabetical order 
by suffixes). Some entries may describe several routines, commands, etc. In 
such cases, the entry appears only once, alphabetized under its "primary" 
name, the name that appears at the upper corners of each manual page. 

All entries are based on a common format, not all of whose parts always 
appear: 

■ The NAME part gives the name(s) of the entry and briefly states its 
purpose. 

■ The SYNOPSIS part summarizes the use of the program being 
described. A few conventions are used, particularly in Section 2 (Sys- 
tem Calls): 

□ Boldface strings are literals and are to be typed just as they 
appear. 

□ Italic strings usually represent substitutable argument prototypes 
and program names found elsewhere in the manual. 

□ Square brackets [] around an argument prototype indicate that the 
argument is optional. When an argument prototype is given as 
"name" or "file", it usually refers to a file name. 

□ ElUpses ... are used to show that the previous argument prototype 
may be repeated. 

□ A final convention is used by the commands themselves. An 
argument beginning with a minus - or plus H- is often taken to be 
some sort of flag argument, even if it appears in a position where a 
file name could appear. Therefore, it is unwise to have files whose 
names begin with - or +. 
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■ The DESCRIPTION part describes the utility. 

■ The EXAMPLE(S) part gives example(s) of usage, where appropriate. 

■ The FILES part gives the file names that are built into the program. 

■ The SEE ALSO part gives pointers to related information. 

■ The DIAGNOSTICS part discusses the diagnostic messages that may be 
produced. Messages that are intended to be self-explanatory are not 
listed. 

■ The NOTES part gives generally "helpful hints" about the use of the 
utility. 

■ The WARNINGS part points out potential pitfalls. 

■ The BUGS part gives known bugs and deficiencies. 

■ The CAVEATS part gives details of the implementation that might 
affect usage. 

A "Table of Contents" and a "Permuted Index" derived from that table 
precede Section 1. The "Permuted Index" is a list of keywords, given in the 
second of three columns, together with the context in which each keyword is 
found. Keywords are either topical keywords or the names of manual entries. 
Entries are identified with their section numbers shown in parentheses. This 
is important because there is considerable duplication of names among the 
sections, arising principally from components that exist only to exercise a par- 
ticular system call. The right column lists the name of the manual page on 
which each keyword may be found. The left column contains useful informa- 
tion about the keyword. 
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NAME 

intro - introduction to programming commands 

DESCRIPTION . 

This section describes, in alphabetical order, commands available for your 
computer. The top of each page indicates the utilities package to which the 
command belongs. The packages are: 

Base System 

C Software Development Set 
Extended Terminal Interface 

COMMAND SYNTAX 

Unless otherwise noted, the commands described accept options and other 
arguments according to the following syntax: 
name [option{s)] [cmdarg(s)] 
where: 

name is the name of an executable file 

option is - noargletter{s) or 
- argletterooptarg 

where: 

noargletter is a single letter representing an option without an 
option-argument 

argletter is a single letter representing an option requiring an 

option-argument 

<> is optional white space 

optarg is an option-argument (character string) satisfying the 
preceding argletter. 

cmdarg is a path name (or other command argument) not beginning with 
or by itself indicating the standard input. 

Throughout the manual pages there are references to TMPDIK BINDIR, 
INCDIRr LIBDIR, and LLIBDIR, These represent directory names whose 
value is specified on each manual page as necessary. For example, TMPDIR 
might refer to /tmp or /usr/tmp. These are not environment variables and 
cannot be set. [There is also an environment variable called TMPDIR 
which can be set. See tmpnam(3S).] 

SEE ALSO 

exit(2), wait(2), getopt(3C). 

getopts(l) in the User's/System Administrator's Reference Manual. 
Programmer's Guide. 
DIAGNOSTICS 

Upon termination, each command returns two bytes of status, one supphed 
by the system and giving the cause for termination and (in the case of "nor- 
mal" termination) one supplied by the program [see wait(2) and exit{2)]. 
The former byte is for normal termination; the latter is customarily for 
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successful execution and non-zero to indicate troubles such as erroneous 
parameters, or bad or inaccessible data. It is called variously "exit code/' 
"exit status/' or "return code" and is described only where special conven- 
tions are involved. 

WARNINGS 

Some commands produce unexpected results when processing files contain- 
ing null characters. These commands often treat text input lines as strings 
and therefore become confused upon encountering a null character (the 
string terminator) within a line. 
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NAME 

admin - create and administer SCCS files 
SYNOPSIS 

admin [-n] [-i[name]] [-rrel] [-t[name]] [-fflag[flag-val]] [-dflag[flag-val]] 
[-alogin] [-elogin] [-m[mrlist]] [-y[comment]] [-h] [-z] files 

DESCRIPTION 

The admin command is used to create new SCCS files and change parame- 
ters of existing ones. Arguments to admin, which may appear in any order, 
consist of keyletter arguments that begin with a hyphen (-), and named files 
(note that SCCS file names must begin with the characters s.). If a named 
file does not exist, it is created, and its parameters are initialized according 
to the specified keyletter arguments. Parameters not initialized by a 
keyletter argument are assigned a default value. If a named file does exist, 
parameters corresponding to specified keyletter arguments are changed, and 
other parameters are left as is. 

If a directory is named, admin behaves as though each file in the directory 
were specified as a named file, except that non-SCCS files (last component 
of the path name does not begin with s.) and unreadable files are silently 
ignored. If a name of - is given, the standard input is read; each line of the 
standard input is taken to be the name of an SCCS file to be processed. 
Again, non-SCCS files and unreadable files are silently ignored. 

The keyletter arguments are as follows. Each is explained as though only 
one named file is to be processed since the effects of the arguments apply 
independently to each named file. 

-n This keyletter indicates that a new SCCS file is to be created. 

-i[name] The name of a file from which the text for a new SCCS file is 
to be taken. The text constitutes the first delta of the file 
(see -r keyletter for delta numbering scheme). If the -i 
keyletter is used but the file name is omitted, the text is 
obtained by reading the standard input until an end-of-file is 
encountered. If this keyletter is omitted, then the SCCS file is 
created empty. Only one SCCS file may be created by an 
admin command on which the -i keyletter is supplied. 
Using a single admin to create two or more SCCS files 
requires that they be created empty (no -i keyletter). Note 
that the -i keyletter implies the -n keyletter. 

-rrel The re/ease into which the initial delta is inserted. This 

keyletter may be used only if the -i keyletter is also used. If 
the -r keyletter is not used, the initial delta is inserted into 
release 1. The level of the initial delta is always 1 (by 
default initial deltas are named 1.1). 

-i[name] The name of a file from which descriptive text for the SCCS 

file is to be taken. If the -t keyletter is used and admin is 
creating a new SCCS file (the -n and/or -i keyletters also 
used), the descriptive text file name must also be supplied. 
In the case of existing SCCS files: (1) a -t keyletter without a 
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file name causes removal of descriptive text (if any) currently 
in the SCCS file, and (2) a -t keyletter with a file name 
causes text (if any) in the named file to replace the descrip- 
tive text (if any) currently in the SCCS file. 

-{flag This keyletter specifies a flag, and, possibly, a value for the 

flag, to be placed in the SCCS file. Several f keyletters may 
be supplied on a single admin command line. The allowable 
flags and their values are: 

b Allows use of the -b keyletter on a get (1) command 
to create branch deltas. 

cceil The highest release (i.e., "ceiling"), a number greater 
than but less than or equal to 9999, which may be 
retrieved by a get{l) command for editing. The 
default value for an unspecified c flag is 9999. 

{floor The lowest release (i.e., "floor"), a number greater 
than but less than 9999, which may be retrieved 
by a get{l) command for editing. The default value 
for an unspecified f flag is 1. 

dSID The default delta number (SIDs+1) to be used by a 
get(l) command. 

i[str] Causes the "No id keywords (ge6)" message issued 
by get{l) or delta(l) to be treated as a fatal error. In 
the absence of this flag, the message is only a warn- 
ing. The message is issued if no SCCS identification 
keywords [see get{l)] are found in the text retrieved 
or stored in the SCCS file. If a value is supplied, the 
keywords must exactly match the given string; how- 
ever, the string must contain a keyword and no 
embedded newlines. 

j Allows concurrent get(l) commands for editing on 

the same SID of an SCCS file. This allows multiple 
concurrent updates to the same version of the SCCS 
file. 

A list of releases to which deltas can no longer be 
made (get -e against one of these "locked" releases 
fails). The list has the following syntax: 

::= <range> I <list> , <range> 
<range>'"::= I a 

The character a in the list is equivalent to specifying 
all releases for the named SCCS file. 

n Causes delta{l) to create a "null" delta in each of 
those releases (if any) being skipped when a delta is 
made in a new release (e.g., in making delta 5.1 after 
delta 2.7, releases 3 and 4 are skipped). These null 
deltas serve as "anchor points" so that branch deltas 
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may later be created from them. The absence of this 
flag causes skipped releases to be nonexistent in the 
sees file, preventing branch deltas from being 
created from them in the future. 

User-definable text substituted for all occurrences of 
the %Q% keyword in SCCS file text retrieved by 

gem 

Module name of the SCCS file substituted for all 
occurrences of the %M% keyword in SCCS file text 
retrieved by get{l). If the m flag is not specified, the 
value assigned is the name of the SCCS file with the 
leading s. removed. 

Type of module in the SCCS file substituted for all 
occurrences of %Y% keyword in SCCS file text 
retrieved by get{l). 

Causes delta{l) to prompt for Modification Request 
(MR) numbers as the reason for creating a delta. The 
optional value specifies the name of an MR number 
validity checking program [see delta {!)]. (If this flag 
is set when creating an SCCS file, the m keyletter 
must also be used even if its value is null.) 

-dflag Causes removal (deletion) of the specified flag from an SCCS 

file. The -d keyletter may be specified only when processing 
existing SCCS files. Several -d keyletters may be supplied on 
a single admin command. See the -f keyletter for allowable 
flag names. 

Hist A list of releases to be "unlocked." See the -f 
keyletter for a description of the 1 flag and the syn- 
tax of a list. 

-Silogin A login name or numerical UNIX system group ID to be added 

to the list of users which may make deltas (changes) to the 
SCCS file. A group ID is equivalent to specifying all login 
names common to that group ID. Several a keyletters may 
be used on a single admin command line. As many logins or 
numerical group IDs as desired may be on the list simultane- 
ously. If the list of users is empty, then anyone may add 
deltas. If login or group ID is preceded by a ! it is to be 
denied permission to make deltas. 

-elogin A login name or numerical group ID to be erased from the list 

of users allowed to make deltas (changes) to the SCCS file. 
Specifying a group ID is equivalent to specifying all login 
names common to that group ID. Several e keyletters may 
be used on a single admin command line. 
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The list of Modification Requests (MR) numbers is inserted 
into the SCCS file as the reason for creating the initial delta 
in a manner identical to delta{l). The v flag must be set; the 
MR numbers are validated if the v flag has a value (the name 
of an MR number validation program). Diagnostics v^ill occur 
if the V flag is not set or MR validation fails. 

The comment text is inserted into the SCCS file as a comment 
for the initial delta in a manner identical to that of delta{l). 
Omission of the -y keyletter results in a default comment 
line being inserted in the form: 

date and time created YY/MM/DD HH:MM:SS by login 

The -y keyletter is valid only if the -i and/or -n keyletters 
are specified (i.e., a new SCCS file is being created). 

Causes admin to check the structure of the SCCS file [see 
sccsfile{5)], and to compare a nev^ly computed check-sum 
(the sum of all the characters in the SCCS file except those in 
the first line) vnth the check-sum that is stored in the first 
line of the SCCS file. Appropriate error diagnostics are pro- 
duced. 

This keyletter inhibits v^riting on the file, so that it nullifies 
the effect of any other keyletters supplied, and is, therefore, 
only meaningful when processing existing files. 

-z The SCCS file check-sum is recomputed and stored in the 

first line of the SCCS file (see -h, above). 

Note that use of this keyletter on a truly corrupted file may 
prevent future detection of the corruption. 

The last component of all SCCS file names must be of the form s.file-name. 
New SCCS files are given mode 444 [see chmod(l)]. Write permission in the 
pertinent directory is, of course, required to create a file. All writing done 
by admin is to a temporary x-file, called x.file-name [see get(l)] created with 
mode 444 if the admin command is creating a new SCCS file, or with the 
same mode as the SCCS file if it exists. After successful execution of admin, 
the SCCS file is removed (if it exists), and the x-file is renamed with the 
name of the SCCS file. This ensures that changes are made to the SCCS file 
only if no errors occurred. 

It is recommended that directories containing SCCS files be mode 755 and 
that SCCS files themselves be mode 444. The mode of the directories allows 
only the owner to modify SCCS files contained in the directories. The mode 
of the SCCS files prevents any modification at all except by SCCS com- 
mands. 

If it should be necessary to patch an SCCS file for any reason, the mode 
may be changed to 644 by the owner allowing use of ed(l). Care must be 
taken! The edited file should always be processed by an admin -h to check 
for corruption followed by an admin -z to generate a proper check-sum. 
Another admin -h is recommended to ensure the SCCS file is valid. 
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The admin command also makes use of a transient lock file (called z,file- 
name), which is used to prevent simultaneous updates to the SCCS file by 
different users. See get{\) for further information. 

FILES 

g-file Existed before the execution of delta; removed after com- 

pletion of delta. 

p-file Existed before the execution of delta; may exist after com- 

pletion of delta. 

q-file Created during the execution of delta; removed after com- 

pletion of delta. 

x-file Created during the execution of delta; renamed to SCCS file 

after completion of delta. 

z-file Created during the execution of delta; removed during the 

execution of delta. 

d-file Created during the execution of delta; removed after com- 

pletion of delta. 

/usr/bin/bdiff Program to compute differences betv^een the "gotten" file 
and the g-file. 

SEE ALSO 

delta(l), get(l), prs(l), what(l), sccsfile(4). 

ed(l), in the User's /System Administrator's Reference Manual. 
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NAME 

ar - archive and library maintainer for portable archives 
SYNOPSIS 

ar key [keyarg] [posname] afile [name] ... 
DESCRIPTION 

The ar command maintains groups of files combined into a single archive 
file. Its main use is to create and update library files as used by the link 
editor. It can be used, though, for any similar purpose. The magic string 
and the file headers used by ar consist of printable ASCII characters. If an 
archive is composed of printable files, the entire archive is printable. 
Archives of text files created by ar are portable between implementations of 
System V. 

When ar creates an archive, it creates headers in a format that is portable 
across all machines. The portable archive format and structure is described 
in detail in flr(4). The archive symbol table [described in ar(4)] is used by 
the link editor [ld{l)] to effect multiple passes over libraries of object files in 
an efficient manner. An archive symbol table is only created and main- 
tained by ar when there is at least one object file in the archive. The 
archive symbol table is in a specially named file that is always the first file 
in the archive. This file is never mentioned nor is it accessible to the user. 
Whenever the ar{l) command is used to create or update the contents of 
such an archive, the symbol table is rebuilt. The s option, described in the 
following text, will force the symbol table to be rebuilt. 

Unlike command options, the command key is a required part of ar's com- 
mand line. The key (which may begin with a -) is formed with one of the 
following letters: drqtpmx. Arguments to the key, alternatively, are made 
with one or more of the following set: vuaibcls. Posname is an archive 
member name used as a reference point in positioning other files in the 
archive. Afile is the archive file. The names are constituent files in the 
archive file. The meanings of the key characters are as follows: 

d Delete the named files from the archive file. 

r Replace the named files in the archive file. If the optional character 

u is used with r, then only those files with dates of modification 
later than the archive files are replaced. If an optional positioning 
character from the set abi is used, then the posname argument must 
be present and specify that new files are to be placed after (a) or 
before (b or i) posname. Otherwise new files are placed at the end. 

q Quickly append the named files to the end of the archive file. 
Optional positioning characters are invalid. The command does not 
check whether the added members are already in the archive. This 
option is useful to avoid quadratic behavior when creating a large 
archive piece-by-piece. Unchecked, the file may grow exponentially 
up to the second degree. 

t Print a table of contents of the archive file. If no names are given, 

all files in the archive are tabled. If names are given, only those 
files are tabled. 
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p Print the named files in the archive. 

m Move the named files to the end of the archive. If a positioning 
character is present, then the posname argument must be present 
and, as in r, specify where the files are to be moved. 

X Extract the named files. If no names are given, all files in the 
archive are extracted. In neither case does x alter the archive file. 

The meanings of the key arguments are as follows: 

V Give a verbose file-by-file description of the making of a new 
archive file from the old archive and the constituent files. When 
used with t, give a long listing of all information about the files. 
When used with x, precede each file with a name. 

c Suppress the message that is produced by default when afile is 

created. 

1 Place temporary files in the local (current working) directory rather 

than in the default temporary directory, TMPDIR. 

s Force the regeneration of the archive symbol table even if ar(l) is 

not invoked with a command which will modify the archive con- 
tents. This command is useful to restore the archive symbol table 
after the strip{l) command has been used on the archive. 

FILES 

$TMPDIR/* temporary files 

$TMPDIR is usually /usr/tmp but can be redefined by setting the environ- 
ment variable TMPDIR [see tempnamQ in tmpnam(3S)]. 

SEE ALSO 

ld(l), lorder(l), strip(l), tsort(l), tmpnam(3S), a.out(4), ar{4). 

NOTES 

If the same file is mentioned twice in an argument list, it may be put in the 
archive twice. 
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NAME 

as - common assembler 

SYNOPSIS 

as [options] file name 

DESCRIPTION 

The as command assembles the named file. The following flags may be 
specified in any order: 

-o oh j file Put the output of the assembly in objfile. By default, the out- 
put file name is formed by removing the .8 suffix, if there is 
one, from the input file name and appending a .o suffix. 

-n Turn off long/short address optimization. By default, address 

optimization takes place. 

-m Run the m4 macro processor on the input to the assembler. 

-R Remove (unlink) the input file after assembly is completed. 

-dl Do not produce line number information in the object file. 

-V Write the version number of the assembler being run on the 

standard error output. 

-Y [md\,dir Find the m4 preprocessor (m) and/or the file of predefined 
macros (d) in directory dir instead of in the customary place. 

FILES 

TMPDIR/* temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environ- 
ment variable TMPDIR [see tempnamQ in tmpnam{3S)]. 

SEE ALSO 

cc(l), ld(l), m4(l), nm(l), strip(l), tmpnam(3S), a.out(4). 

NOTES 

Wherever possible, the assembler should be accessed through a compilation 
system interface program [such as cc(l)]. 

WARNING 

If the -m (m4 macro processor invocation) option is used, keywords for m4 
[see m4(l)] cannot be used as symbols (variables, functions, labels) in the 
input file since m4 cannot determine which are assembler symbols and 
which are real w4 macros. 

BUGS 

The .align assembler directive may not work in the text section when 
optimization is performed. 

CAVEATS 

Arithmetic expressions may only have one forward referenced symbol per 
expression. 
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NAME 

cb - C program beautifier 

SYNOPSIS 

cb [ -s ] [ -j ] [ -1 leng ] [ file ... ] 

DESCRIPTION 

The cb command reads C programs either from its arguments or from the 
standard input and writes them on the standard output with spacing and 
indentation that display the structure of the code. Under default options, cb 
preserves all user new-lines. 

The cb command accepts the following options: 

-s Canonicalizes the code to the style of Kemighan and Ritchie in 

The C Programming Language. 

-j Causes split lines to be put back together. 

-1 leng Causes cb to split lines that are longer than leng. 

SEE ALSO 

cc(l). 

Kemighan, B. W., and Ritchie, D. M., The C Programming Language, 
Prentice-Hall, 1978. 

BUGS 

Punctuation that is hidden in preprocessor statements will cause indentation 
errors. 
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NAME 

cc - C compiler 

SYNOPSIS 

cc [ options ] files 

DESCRIPTION 

The cc command is the interface to the C Compilation System. The compi- 
lation tools consist of a preprocessor, compiler, optimizer, assembler, and 
link editor. The cc command processes the supplied options and then exe- 
cutes the various tools vsdth the proper arguments. The cc command accepts 
several types of files as arguments. 

Files whose names end with .c are taken to be C source programs and may 
be preprocessed, compiled, optimized, assembled, and link edited. The 
compilation process may be stopped after the completion of any pass if the 
appropriate options are supplied. If the compilation process runs through 
the assembler, then an object program is produced and is left in the file 
whose name is that of the source with .o substituted for .c. However, the .o 
file is normally deleted if a single C program is compiled and then immedi- 
ately link edited. In the same way, files whose names end in .s are taken to 
be assembly source programs and may be assembled and link edited; and 
files whose names end in .i are taken to be preprocessed C source programs 
and may be compiled, optimized, assembled, and link edited. Files whose 
names do not end in .c, .s, or .i are handed to the link editor. 

Since the cc command usually creates files in the current directory during 
the compilation process, it is necessary to run the cc command in a directory 
in which a file can be created. 

The foUov^ng options are interpreted by cc: 

-c Suppress the link editing phase of the compilation and do not 
remove any produced object files. 

-ds Do not generate symbol attribute information for the symbolic 
debugger. 

-dl Do not generate symbolic debugging line number information. This 
and the above flag may be used in conjunction as -dsl (-dsl is the 
default unless the -g flag is given). 

-g Cause the compiler to generate additional information needed for 
the use of sdb(l). 

-o outfile 

Produce an output object file by the name outfile. The name of the 
default file is a.out. This is a link editor option. 

-p Arrange for the compiler to produce code that counts the number of 
times each routine is called; also, if link editing takes place, profiled 
versions of libca and libm.a (with -Im option) are linked and 
monitor(3C) is automatically called. A mon.out file will then be 
produced at normal termination of execution of the object program. 
An execution profile can then be generated by use of prof{l). 
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-qp Arrange for profiled code to be produced where the p argument 
produces identical results to the -p option [allows profiling with 
prof(l)l 

-E Run only cpp{l) on the named C programs, and send the result to 
the standard output. 

-H Print out on stderr the path name of each file included during the 
current compilation. 

-O Do compilation phase optimization. This option will not have any 
effect on .s files. 

-P Run only cpp{l) on the named C programs and leave the result in 
corresponding files suffixed .i. This option is passed to cpp(l). 

-S Compile and do not assemble the named C programs, and leave the 
assembler-language output in corresponding files suffixed .s. 

-V Print the version of the compiler, optimizer, assembler and/or link 
editor that is invoked. 

-Wc,argl[,arg2...] 

Hand off the argument[s] argi to pass c where c is one of [p02al] 
indicating the preprocessor, compiler, optimizer, assembler, or link 
editor, respectively. For example: -Wa,-m passes -m to the assem- 
bler. 

-Y [p02aiSlLV],dirname 

Specify a new path name, dirmme, for the locations of the tools and 
directories designated in the first argument. [p02alSILU] represents: 

p preprocessor 

compiler 
2 optimizer 
a assembler 

1 link editor 

S directory containing the start-up routines 

I default include directory searched by cpp{\) 

L first default library directory searched by ld{\) 

U second default library directory searched by ld{\) 

If the location of a tool is being specified, then the new path name 
for the tool will be dimame/tool. If more than one -Y option is 
applied to any one tool or directory, then the last occurrence holds. 

-Zp[ll2l4] 

Packs structure members in memory. Normally, structure members 
are aligned as follows: items of type char are byte-aligned, items of 
type short are aligned on two-byte boundaries, and all other types 
of structure members are word-aligned. 

Specifying an option to -Zp will force alignment on the given byte 
boundary. If no option is used with -Zp, structure members will be 
packed on one-byte boundaries. The alignment may be altered with 
the #pragma pack preprocessor directive. 



- 2 - 



CC(1) 



(C Software Development Set) 



CC(1) 



The cc command also recognizes -C, -D, -I, and -U and passes these 
options and their arguments directly to the preprocessor without using the 
-W option. Similarly, the cc command recognizes -a, -1, -m, -r, -s, -t, -u, 
-X, -z, -L, -M, and -V and passes these options and their arguments 
directly to the loader. See the manual pages for cpp{l) and ld{l) for 
descriptions. 

Other arguments are taken to be C compatible object programs, typically 
produced by an earlier cc run, or perhaps libraries of C compatible routines 
and are passed directly to the link editor. These programs, together with 
the results of any compilations specified, are link edited (in the order given) 
to produce an executable program with name a.out unless the -o option of 
the link editor is used. 

If the cc command is put in a file prefixcc the prefix will be parsed off the 
command and used to call the tools, i.e., prefixtooh For example, OLDcc 
will call OLDcpp, OLDcomp, OLDoptim, OLDas, and OLDld and will link 
OLDcrtl.o. Therefore, one MUST be careful when moving the cc command 
around. The prefix will apply to the preprocessor, compiler, optimizer, 
assembler, link editor, and the start-up routines. 

The C language standard was extended to allow arbitrary length variable 
names. The option pair "-Wp,-T -WO,-XT" will cause cc to truncate arbi- 
trary length variable names. 



LIBDIR is usually /lib. 
BINDIR is usually /bin. 

TMPDIR is usually /usr/tmp but can be redefined by setting the environ- 
ment variable TMPDIR [see tempmmQ in tmpnam{3S)]. 



as(l), ld(l), cpp(l), gencc(lM), lint(l), prof(l), sdb(l), tmpnam(3S). 

Kemighan, B. W., and Ritchie, D. M., The C Programming Language, 
Prentice-Hall, 1978. 



FILES 



file.c 
file.i 
file.o 
file.s 
a.out 

L7BD/R/*crtl.o 

LJBD/R/crtn.o 

TMPDIR/* 

LIBDIR/cpp 

LIBDIR/comp 

LJBD/R/optim 

BINDIR/as 

BINDIR/\d 

LIBDJR/libc.a 

LJBD/R/libc_s.a 



C source file 

preprocessed C source file 
object file 

assembly language file 
link edited output 
start-up routine 
start-up routine 
temporary files 
preprocessor, cpp{l) 
compiler 
optimizer 
assembler, fls(l) 
link editor, ld(l) 
standard C library 
standard C shared library 



SEE ALSO 
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DIAGNOSTICS 

The diagnostics produced by the C compiler are sometimes cryptic. 

NOTES 

By default, the return value from a compiled C program is completely ran- 
dom. The only two guaranteed ways to return a specific value is to expli- 
citly call exit(2) or to leave the function main() with a "return expression;" 
construct. 
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NAME 

ccoff - convert a COFF file 

SYNOPSIS 

ccoff [-r] [-v] file ... 

DESCRIPTION 

The ccoff command converts a COFF file by byte-swapping all multi-byte 
integers in the file. Thus, if the COFF file has been built by a cross com- 
piler running on a big-endian development machine (Motorola 68000, etc.), 
ccoff will convert the file to a format suitable for running on the target 
(80386) machine. The ccoff command will convert relocated executables, 
non-relocated objects, and archives (libraries). The -r flag performs the 
reverse conversion, so that a file that has already been run through ccoff can 
be restored to its original state; or a file that has been built on a target 
machine can be manipulated on the development machine. The -v flag 
causes ccoff to operate verbosely. 

SEE ALSO 

convert(l) 
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NAME 

cdc - change the delta commentary of an SCCS delta 
SYNOPSIS 

cdc -rSID [-m[mrlist]] [-y[comment]] files 
DESCRIPTION 

The cdc command changes the delta commentary, for the SID (SCCS IDentif- 
ication string) specified by the -r keyletter, of each named SCCS file. 

Delta commentary is defined to be the Modification Request (MR) and com- 
ment information normally specified via the delta{l) command (-m and -y 
keyletters). 

If a directory is named, cdc behaves as though each file in the directory 
were specified as a named file, except that non-SCCS files (last component 
of the path name does not begin with s.) and unreadable files are silently 
ignored. If a name of - is given, the standard input is read (see WARNINGS) 
and each line of the standard input is taken to be the name of an SCCS file 
to be processed. 

Arguments to cdc, which may appear in any order, consist of keyletter argu- 
ments and file names. 

All the described keyletter arguments apply independently to each named 
file: 

-rSlD Used to specify the SCCS /Dentification (SID) string of a 

delta for which the delta commentary is to be changed. 

-mmrlist If the SCCS file has the v flag set [see admin{\)] then a 
list of MR numbers to be added and/or deleted in the 
delta commentary of the SID specified by the -r keyletter 
may be supplied. A null MR list has no effect. 

MR entries are added to the list of MRs in the same 
manner as that of delta{\). In order to delete an MR, pre- 
cede the MR number with the character ! (see EXAM- 
PLES), If the MR to be deleted is currently in the list of 
MRS, it is removed and changed into a "comment" line. 
A list of all deleted MRs is placed in the comment section 
of the delta commentary and preceded by a comment line 
stating that they were deleted. 

If -m is not used and the standard input is a terminal, 
the prompt MRs? is issued on the standard output before 
the standard input is read; if the standard input is not a 
terminal, no prompt is issued. The MRs? prompt always 
precedes the comments? prompt (see -y keyletter). 
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MRS in a list are separated by blanks and/or tab charac- 
ters. An unescaped new-line character terminates the MR 
list. 

Note that if the v flag has a value [see admin(l)], it is 
taken to be the name of a program (or shell procedure) 
which validates the correctness of the MR numbers. If a 
non-zero exit status is returned from the MR number vali- 
dation program, cdc terminates and the delta commentary 
remains unchanged. 

-y[comment] Arbitrary text used to replace the cominent{s) already 
existing for the delta specified by the -r keyletter. The 
previous comments are kept and preceded by a comment 
line stating that they were changed. A null comment has 
no effect. 

If -y is not specified and the standard input is a terminal, 
the prompt comments? is issued on the standard output 
before the standard input is read; if the standard input is 
not a terminal, no prompt is issued. An unescaped new- 
line character terminates the comment text. 

Simply stated, the rules are: 

(1) If you made the delta, you can change its delta commentary, 
or 

(2) If you own the file and directory, you can modify the delta commen- 
tary. 

EXAMPLES 

cdc -rl.6 -m"bl78-12345 !bl77-54321 bl79-00001" -ytrouble s.file 

adds bl78-12345 and bl79-00001 to the MR list, removes bl77-54321 from 
the MR list, and adds the comment trouble to delta 1.6 of s.file. 

cdc -rl.6 s.file 

MRS? !bl77-54321 bl78-12345 bl79-00001 
comments? trouble 

does the same thing. 

FILES 

x-file [see delta{l)] 
z-file [see delta{l)] 

SEE ALSO 

admin(l), delta(l), get(l), prs(l), sccsfile(4). 
WARNINGS 

If sees file names are supplied to the cdc command via the standard input 
(- on the command line), then the -m and -y keyletters must also be used. 
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NAME 

cflow - generate C flowgraph 

SYNOPSIS 

cflow [-r] [-ix] [-i— ] [-dnum] files 

DESCRIPTION 

The cflow command analyzes a collection of C, yacc, lex, assembler, and 
object files and attempts to build a graph charting the external references. 
Files suffixed with .y, .1, and .c are yacced, lexed, and C-preprocessed as 
appropriate. The results of the preprocessed files, and files suffixed with .i, 
are then run through the first pass of lint{l). Files suffixed with .s are 
assembled. Assembled files, and files suffixed with .o, have information 
extracted from their symbol tables. The results are collected and turned into 
a graph of external references which is displayed upon the standard output. 

Each line of output begins with a reference number, followed by a suitable 
number of tabs indicating the level, then the name of the global symbol fol- 
lowed by a colon and its definition. Normally only function names that do 
not begin with an underscore are listed (see the -i options below). For 
information extracted from C source, the definition consists of an abstract 
type declaration (e.g., char *), and, delimited by angle brackets, the name of 
the source file and the line number where the definition was found. Defini- 
tions extracted from object files indicate the file name and location counter 
under which the symbol appeared (e.g., text). Leading underscores in C- 
style external names are deleted. 

Once a definition of a name has been printed, subsequent references to that 
name contain only the reference number of the line where the definition 
may be found. For undefined references, only <> is printed. 

As an example, given the following in file.c: 



int i; 



main() 

{ 



f() 

{ 



f(); 
g(); 
f(); 



i = h(); 
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the command 



cflow -ix file.c 



produces the output 



1 
2 
3 
4 
5 



main: int(), <file.c 4> 

f: into, <file.c 11> 
h: <> 

i: int, <file.c 1> 

g: <> 



When the nesting level becomes too deep, the output of cflow can be piped 
to pr{l), using the -e option, to compress the tab expansion to something 
less than every eight spaces. 

In addition to the -D, -I, and -U options [which are interpreted just as they 
are by cc(l) and cpp(l)l the foUovdng options are interpreted by cflow: 

-r Reverse the "callerrcallee" relationship producing an inverted listing 
shovy^ing the callers of each function. The listing is also sorted in 
lexicographical order by callee. 

-ix Include external and static data symbols. The default is to include 
only functions in the flowgraph. 

-L_ Include names that begin with an underscore. The default is to 
exclude these functions (and data if -ix is used). 

-dnum The mm decimal integer indicates the depth at v^hich the flow- 
graph is cut off. By default this is a very large number. Attempts 
to set the cutoff depth to a nonpositive integer will be ignored. 

SEE ALSO 

as(l), cc(l), cpp{l), lex(l), lint(l), nm(l), yacc(l). 

pr(l) in the User's /System Administrator's Reference Manual 

DIAGNOSTICS 

Complains about bad options. Complains about multiple definitions and 
only believes the first. Other messages may come from the various pro- 
grams used (e.g., the C-preprocessor). 

BUGS 

Files produced by lex{l) and yacc(l) cause the reordering of line number 
declarations which can confuse cflow. To get proper results, feed cflow the 
yacc or lex input. 
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NAME 

chkshlib - compare shared libraries tool 
SYNOPSIS 

chkshlib [-b] [-i] [-n] [-v] filel [me2 fUeS ... ] 
DESCRIPTION 

chkshlib checks for compatibility between files. Input files can be combina- 
tions of host shared libraries, non-stripped target shared libraries, and non- 
stripped executable files. A file is compatible with another file if every 
library symbol in it that should be matched is matched in the second (i.e., 
the symbol exists and has the same address in both files). The path name 
for the target shared library in both files must be identical (unless the -i 
option is set). 

It is possible for filel to be compatible with filel without the reverse also 
being true. 

If one incompatibility is found it is reported to stdout and processing stops 
(unless the -v option is set). 

The options to chkshlib are: 

-V Cause verbose reporting of all incompatibilities to stdout. 

-b If there are symbols found in filel that are not in the bounds of 
filel, report warning messages to stderr. 

-i Turn off the restriction that the path names for the target shared 
library need to be identical for two files to be compatible. 

-n Indicate that there are exactly two input files, which are target 
shared libraries, where the first references symbols in the second 
("includes" the second). 

The output of chkshlib depends upon the input. If the first input file is an 
executable file and the other input files, if any, are target shared libraries, 
the output states whether or not the executable file can execute using each 
target shared library. If there are no target shared libraries supplied, 
chkshlib performs the compatibility check against the target shared libraries 
specified in the .lib section of the executable file. 

If the first input file is an executable file and the other input file(s) is a host 
shared library, the output states whether or not the executable file could 
have been produced using each host. 

If one input file is a host shared library and the other input file, if any, is a 
target shared library, the output states whether or not the host shared 
library could produce executable files that will run with the target shared 
library. If no target shared library is supplied, then chkshlib performs the 
compatibility check against the target specified in the .lib section of the 
library definition file found in the host. 

If both input files are target shared libraries or both input files are host 
shared libraries, the output states whether or not the first file could replace 
the second and vice versa. 
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If both input files are target libraries and the -n option is set, the output 
states if the first file references symbols in the second file ("includes" the 
second). 

Compatibility of all other combinations of host shared libraries, target 
shared libraries, and executable files has no useful meaning, and these other 
combinations of files are not accepted as valid input to chkshlib. 

SEE ALSO 

mkshlib(l). 

" Shared Libraries " chapter in the UNIX System V Programmer's Guide, 
DIAGNOSTICS 

Exit status is if no incompatibilities are found, 1 if an incompatibility is 
found, and 2 if a processing error occurs. 

CAVEAT 

chkshlib requires that you use the -i option whenever you use the -n option. 

Standard binaries distributed with the UNIX system are stripped, and 
chkshlib cannot be used with them. 
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NAME 

comb - combine SCCS deltas 

SYNOPSIS 

comb -o -s [-pSID] [-clist] files 

DESCRIPTION 

The comb command generates a shell procedure [see sh{l)] which, when 
run, will reconstruct the given SCCS files. The reconstructed files will, 
hopefully, be smaller than the original files. The arguments may be speci- 
fied in any order, but all keyletter arguments apply to all named SCCS files. 
If a directory is named, comb behaves as though each file in the directory 
were specified as a named file, except that non-SCCS files (last component 
of the path name does not begin with s.) and unreadable files are silently 
ignored. If a name of - is given, the standard input is read; each line of the 
input is taken to be the name of an SCCS file to be processed; non-SCCS 
files and unreadable files are silently ignored. The generated shell pro- 
cedure is written on the standard output. 

The keyletter arguments are as follows. Each is explained as though only 
one named file is to be processed, but the effects of any keyletter argument 
apply independently to each named file. 

-o For each get -e generated, this argument causes the recon- 

structed file to be accessed at the release of the delta to be 
created, otherwise the reconstructed file would be accessed at the 
most recent ancestor. Use of the -o keyletter may decrease the 
size of the reconstructed SCCS file. It may also alter the shape of 
the delta tree of the original file. 

-pSID The SCCS /Dentification string (SID) of the oldest delta to be 
preserved. All older deltas are discarded in the reconstructed 
file. 

-s This argument causes comb to generate a shell procedure which, 

when run, will produce a report giving, for each file: the file 
name, size (in blocks) after combining, original size (also in 
blocks), and percentage change computed by: 

100 * (original - combined) / original 

It is recommended that before any SCCS files are actually com- 
bined, one should use this option to determine exactly how 
much space is saved by the combining process. 

If no keyletter arguments are specified, comb will preserve only leaf deltas 
and the minimal number of ancestors needed to preserve the tree. 

FILES 

S.COMB The name of the reconstructed SCCS file, 

comb????? Temporary. 
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SEE ALSO 

admin(l), delta(l), get(l), prs(l), sccsfile(4). 

sh(l) in the Usefs/System Administrator's Reference Manual 

BUGS 

The comb command may rearrange the shape of the tree of deltas. It may 
not save any space; in fact, it is possible for the reconstructed file to actually 
be larger than the original. 
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NAME 

conv - common object file converter 

SYNOPSIS 

conv [-a] [-o] [-p] -t target [- I files] 

DESCRIPTION 

The conv command converts object files in the common object file format 
from their current byte ordering to the byte ordering of the target machine. 
The converted file is written to file.v. The conv command can be used on 
either the source (sending) or target (receiving) machine. 

Command line options are: 

Indicates that the names of files should be read from the 
standard input. 

-a If the input file is an archive, produce the output file in the 

UNIX System V Release 2.0 portable archive format. 

-o If the input file is an archive, produce the output file in the old 

(pre- UNIX System V) archive format. 

-p If the input file is an archive, produce the output file in the 

UNIX System V Release 1.0 random access archive format. 

-t target Convert the object file to the byte ordering of the machine 
(target) to v^hich the object file is being shipped. This may be 
another host or a target machine. Legal values for target are: 
pdp, vax, ibm, x86, bl6, n3b, mc68, and m32. 

The conv command is meant to ease the problems created by a multi-host, 
cross-compilation development environment. The conv command is best 
used v^ithin a procedure for shipping object files from one machine to 
another. 

The conv command v^U recognize and produce archive files in three for- 
mats: the pre- UNIX System V format, the UNIX System V Release 1.0 ran- 
dom access format, and the UNIX System V Release 2.0 portable ASCII for- 
mat. By default, conv will create the output archive file in the same format 
as the input file. To produce an output file in a different format than the 
input file, use the -a, -o, or -p option. If the output archive format is the 
same as the input format, the archive symbol table will be converted, other- 
wise the symbol table will be stripped from the archive. The ar(l) com- 
mand with its -t and -s options must be used on the target machine to 
recreate the archive symbol table. 

EXAMPLE 

To ship object files from a VAX computer sytem to a 3B2 computer, execute 
the following commands: 

conv -t m32 *.out 

uucp *.out.v my3b2r/rje/ 
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SEE ALSO 

ar(l), convert(l), ar(4), a.out(4). 

DIAGNOSTICS 

The diagnostics are self-explanatory. Fatal diagnostics on the command 
lines cause termination. Fatal diagnostics on an input file cause the pro- 
gram to continue to the next input file. 

CAVEATS 

The conv command will not convert archives from one format to another if 
both the source and target machines have the same byte ordering. The 
UNIX system tool convert(l) should be used for this purpose. 
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NAME 

convert - convert archive files to common formats 

SYNOPSIS 

convert [-x] infile outfile 

DESCRIPTION 

The convert command transforms input infile to output outfile. Infile must 
be a UNIX System V Release 1.0 or XENIX archive file and outfile will be 
the equivalent UNIX System V Release 2.0 archive file. All other types of 
input to the convert command will be passed unmodified from the input file 
to the output file (along vdth appropriate warning messages). 

The -X option is required to convert a XENIX archive. Using this option will 
convert the general archive structure but leave archive members unmodi- 
fied. 

Infile must be different from outfile. 

FILES 

TMPDJR/conv* temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environ- 
ment variable TMPDIR [see tempnami) in tmpnam(3S)]. 

SEE ALSO 

ar(l), tmpnam(3S), a.out(4), ar(4). 
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NAME 

cpp - the C language preprocessor 

SYNOPSIS 

LIBDIR/q>p [option ...] [ifile [ofile]] 

DESCRIPTION 

The C language preprocessor, cpp, is invoked as the first pass of any C 
compilation by the cc(l) command. Thus cpp's output is designed to be in 
a form acceptable as input to the next pass of the C compiler. As the C 
language evolves, cpp and the rest of the C compilation package v^ill be 
modified to follow these changes. Therefore, the use of cpp other than 
through the cc(l) command is not suggested, since the functionality of cpp 
may someday be moved elsevy^here. See m4(l) for a general macro proces- 
sor. 

The cpp command optionally accepts two file names as arguments. Ifile 
and ofile are respectively the input and output for the preprocessor. They 
default to standard input and standard output if not supplied. 

The foUov^ng options to cpp are recognized: 

-P Preprocess the input without producing the line control information 
used by the next pass of the C compiler. 

-C By default, cpp strips C-style comments. If the -C option is speci- 
fied, all comments (except those found on cpp directive lines) are 
passed along. 

-Uname 

Remove any initial definition of name, where name is a reserved 
symbol that is predefined by the particular preprocessor. Following 
is the current list of these possibly reserved symbols. On the 80386, 
Unix and i386 are defined. 



operating system: unix, dmert, gcos, ibm, os, tss 

hardware: 1286, 1386, interdata, pdpll, u370, u3b, 

u3b5, u3b2, u3bl5, u3b20d, vax 
UNIX system variant: RES, RT 
Until): lint 



-Dname 
-Dname=def 

Define name with value def as if by a #define. If no =def is given, 
name is defined with value 1. The -D option has lower precedence 
than the -U option. That is, if the same name is used in both a -U 
option and a -D option, the name will be undefined regardless of 
the order of the options. 

-T The -T option forces cpp to use only the first eight characters to 
distinguish preprocessor symbols and is included for backward com- 
patibility. 

-Idir Change the algorithm for searching for #include files whose names 
do not begin with / to look in dir before looking in the directories 
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on the standard list. Thus, #include files whose names are 
enclosed in " " will be searched for first in the directory of the file 
with the #include line, then in directories named in -I options, and 
last in directories on a standard list. For #include files whose 
names are enclosed in <>, the directory of the file with the 
#include line is not searched. 

-Ydir Use directory dir in place of the standard list of directories when 
searching for #include files. 

-H Print, one per line on standard error, the path names of included 
files. 

Two special names are understood by cpp. The name LINE is 

defined as the current line number (as a decimal integer) as known by cpp, 

and FILE is defined as the current file name (as a C string) as known 

by cpp. They can be used anywhere (including in macros) just as any other 
defined name. 

All cpp directive lines start with # in column 1. Any number of blanks and 
tabs is allowed between the # and the directive. The directives are: 

#define name token-string 

Replace subsequent instances of name with token-string. 

#define name( arg, arg ) token-string 

Notice that there can be no space between name and the (. Replace 
subsequent instances of name followed by a (, a list of comma- 
separated sets of tokens, and a ) followed with token-string. Each 
occurrence of an arg is replaced by the corresponding set of tokens 
in the comma-separated list. When a macro with arguments is 
expanded, the arguments are placed into the expanded token-string 
unchanged. After the entire token-string has been expanded, cpp 
re-starts its scan for names to expand at the beginning of the newly 
created token-string. 

#undef name 

Cause the definition of name (if any) to be forgotten from now on. 
No additional tokens are permitted on the directive line after name. 

#ident string" 

Put string into the .comment section of an object file. 

#include ''filename" 

#include <filename> 

Include at this point the contents of filename (which will then be 
run through cpp). When the <filename> notation is used, filename 
is only searched for in the standard places. See the -I and -Y 
options above for more detail. No additional tokens are permitted 
on the directive line after the final " or >. 

#Iine integer-constant "filename" 

Causes cpp to generate line control information for the next pass of 
the C compiler. Integer-constant is the line number of the next line 
and filename is the file from which it comes. If "filename" is not 
given, the current file name is unchanged. No additional tokens are 
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permitted on the directive line after the optional filename, 

#endif 

Ends a section of lines begun by a test directive (#if, #ifdef, or 
#ifndef). Each test directive must have a matching #endif. No 
additional tokens are permitted on the directive line. 

#ifdef name 

The lines foUovydng will appear in the output if and only if name has 
been the subject of a previous #define without being the subject of 
an intervening #unde£. No additional tokens are permitted on the 
directive line after name . 

#ifndef name 

The lines following will appear in the output if and only if name has 
not been the subject of a previous #define. No additional tokens 
are permitted on the directive line after name . 

#if constant-expression 

Lines following will appear in the output if and only if the 
constant-expression evaluates to non-zero. All binary non- 
assignment C operators, the ?: operator, the unary -, !, and " opera- 
tors are all legal in constant-expression. The precedence of the 
operators is the same as defined by the C language. There is also a 
unary operator defined, which can be used in constant-expression in 
these two forms: defined ( name ) or defined name. This allows 
the utility of #ifdef and #ifndef in a #if directive. Only these 
operators, integer constants, and names which are known by cpp 
should be used in constant-expression. In particular, the sizeof 
operator is not available. 

To test whether either of two symbols, foo and /«m, are defined, use 

#if defined(foo) li defined(fum) 

#elif constant-expression 

An arbitrary number of #elif directives is allowed between a #if, 
#ifdef, or #ifndef directive and a #else or #endif directive. The 
lines following the #elif directive will appear in the output if and 
only if the preceding test directive evaluates to zero, all intervening 
#elif directives evaluate to zero, and the constant-expression evalu- 
ates to non-zero. If constant-expression evaluates to non-zero, all 
succeeding #elif and #else directives will be ignored. Any 
constant-expression allowed in a #if directive is allowed in a #elif 
directive. 

#else The lines following will appear in the output if and only if the 
preceding test directive evaluates to zero, and all intervening #elif 
directives evaluate to zero. No additional tokens are permitted on 
the directive line. 

The test directives and the possible #else directives can be nested. 
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#pragma pack([ll2!4]) 

If an argument is present, subsequent structures will be aligned to 
the given byte boundary. The packing of structure members remains 
in effect until changed or disabled. If no argument is present and 
the -Zp option was used with the cc command, packing reverts to 
the packing specified on the cc command line. If the -Zp option was 
not used with the cc command, structures are aligned to their nor- 
mal settings. 



SEE ALSO 

cc(l), lint(l), m4(l). 

DIAGNOSTICS 

The error messages produced by cpp are intended to be self-explanatory. 
The line number and file name where the error occurred are printed along 
with the diagnostic. 

NOTES 

The unsupported -W option enables the #class directive. If it encounters a 
#class directive, cpp will exit with code 27 after finishing all other process- 
ing. This option provides support for "C with classes." 

Because the standard directory for included files may be different in dif- 
ferent environments, this form of #include directive: 

#include <file.h> 

should be used, rather than one with an absolute path, like: 
#include " /usr/include/f ile .h" 

The cpp command warns about the use of the absolute path name. 



FILES 



INCDIR 



LIBDIR 



standard directory list for #include files, usually 
/usr /include 

usually /lib 
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NAME 

cprs - compress a common object file 

SYNOPSIS 

cprs [-p] filel file2 

DESCRIPTION 

The cprs command reduces the size of a common object file, filel, by 
removing duplicate structure and union descriptors. The reduced file, filel, 
is produced as output. 

The sole option to cprs is: 

-p Print statistical messages including: total number of tags, total dupli- 
cate tags, and total reduction of filel . 

SEE ALSO 

strip(l), a.out(4), syms(4). 
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NAME 

cscope - interactively examine a C program 
SYNOPSIS 

cscope [-f reffile] [-i namefile] [[-I incdir]] [-d] [files] 
DESCRIPTION 

cscope is an interactive screen-oriented tool that helps programmers browse 
through C source code. 

By default, cscope examines the C, yacc, and lex source files in the current 
directory and builds a symbol cross-reference. It then uses this table to find 
references to symbols (including C preprocessor symbols), function declara- 
tions, and function calls. 

cscope builds the symbol cross-reference the first time it is used on the 
source files for the program being browsed. On a subsequent invocation, 
cscope rebuilds the cross-reference only if a source file has changed or the 
list of source files is different. When the cross-reference is rebuilt, the data 
for the unchanged files are copied from the old cross-reference, which 
makes rebuilding much faster than the initial build. 

The following options can appear in any combination: 

-f reffile 

Use reffile as the cross-reference file name instead of the default 
cscope.out. 

-i namefile 

Get the list of files (file names separated by spaces, tabs, or new- 
lines) to browse from namefile. If this option is specified, cscope 
ignores any files appearing on the command line. 

-I incdir 

Look in incdir (before looking in INCDIR, the standard place for 
header files that is normally /usr/include) for any #include files 
whose names do not begin with / and that are not specified on the 
command line or in namefile above. (The #include files may be 
specified with either double quotes or angle brackets.) The incdir 
directory is searched in addition to the current directory (which is 
searched first) and the standard list (which is searched last). If more 
than one occurrence of -I appears, the directories are searched in 
the order they appear on the command line. 

-d Do not update the cross-reference. 

Requesting the Initial Search 

After the cross-reference is ready cscope will display this menu: 

List references to this C symbol: 
Edit this function or #define: 
List functions called by this function: 
List functions calling this function: 
List lines containing this text string: 
Change this text string: 
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Press the TAB key repeatedly to move to the desired input field, type the 
text to search for, and then press the RETURN key. 

Issuing Subsequent Requests 

If the search is successful, any of these single-character commands can be 
used: 

1-9 Edit the file referenced by the given line number. 

SPACE Display next lines. 
-I- Display next lines. 

- Display previous lines, 

e Edit all lines. 

> Append the displayed list of lines to a file. 

At any time these single-character commands can also be used: 

TAB Move to next input field. 

RETURN Move to next input field. 

m Move to next input field. 

p Move to previous input field. 

Search with the last text typed. 

r Rebuild the cross-reference. 

[ Start an interactive shell (type to return to escape). 

1 Redrav^ the screen. 

? Display this list of commands. 

d Exit escape. 

Note: If the first character of the text to be searched for matches one of the 
above commands, escape it by typing a \ (backslash) first. 

Substituting New Text for Old Text 

After the text to be changed has been typed, escape will prompt for the new 
text, and then it will display the lines containing the old text. Select the 
lines to be changed with these single-character commands: 



1-9 Mark or unmark the line to be changed. 

* Mark or unmark all displayed lines to be changed. 

SPACE Display next lines. 

+ Display next lines. 

Display previous lines, 

a Mark all lines to be changed. 

d Change the marked lines and exit. 

ESCAPE Exit without changing the marked lines. 

[ Start an interactive shell (type d to return to escape). 

L Redraw the screen. 

? Display this list of commands. 

ENVIRONMENT VARIABLES 

EDITOR Preferred editor, which defaults to vi{l). 
HOME Home directory, which is automatically set at login. 
SHELL Preferred shell, which defaults to sh{l). 
TERM Terminal type, which must be a screen terminal. 
VIEWER Preferred file display program [such as pg{l)], which overrides 
EDITOR (see above). 
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VPATH 



FILES 



cscope.out 
ncscope.out 



INCDIR 



An ordered list of directory i\ames, separated by colons. It can 
be used by cscope to search for both source and header files, but 
the two types of files have different orders of search. If VPATH 
is set, cscope searches for source files in the directories specified; 
if it is not set, cscope searches only in the current directory. 
cscope searches for header files in the following order: (1) if 
VPATH is set, in directories specified in VPATH and if VPATH is 
not set, in the current directory; (2) in directories specified by 
the -I option (if they exist); and (3) in the standard location for 
header files (normally /usr/include). 

Symbol cross-reference file, which is put in the home direc- 
tory if it cannot be created in the current directory. 
Temporary file containing new cross-reference before it 
replaces the old cross-reference. 

Standard directory for #include files (usually is 
/usr/include). 



WARNINGS 

cscope recognizes function definitions of the form: 
fname blank ( args ) white arg^decs white { 



where: 
fname 
blank 
args 
white 
arg—decs 



is the function name, 

is zero or more spaces or tabs, not including newlines, 
is any string that does not contain a " or a newline, 
is zero or more spaces, tabs, or newlines, and 
are zero or more argument declarations, arg—decs may include 
comments and white space. 

It is not necessary for a function declaration to start at the beginning of a 
line. The return type may precede the function name; cscope will still recog- 
nize the declaration. Function definitions that deviate from this form will 
not be recognized by cscope. 
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NAME 

ctags - create a tags file 
SYNOPSIS 

ctags [ -a ] [ -u ] [ -V ] [ -w ] [ -X ] name ... 
DESCRIPTION 

Ctags makes a tags file for vi{l) from the specified C sources. A tags file 
gives the locations of specified objects (in this case functions) in a group of 
files. Each line of the tags file contains the function name, the file in which 
it is defined, and a scanning pattern used to find the function definition. 
These are given in separate fields on the line, separated by blanks or tabs. 
Using the tags file, vi can quickly find these function definitions. 

If the -X flag is given, ctags produces a list of function names and the line 
number and file name on which each is defined, as well as the text of that 
line, and prints this on the standard output. With the -x option, no tags file 
is created. This is a simple index which can be printed out as an off-line 
readable function index. Files whose name ends in .c or .h are assumed to 
be C source files and are searched for C routine and macro definitions. 

Other options are 

-a Causes specified files to be appended to tags; that is, new values for 

the files are appended to the tags file, 
-u Causes the specified files to be updated in tags; that is, all references to 

them are deleted, and the new values are appended to the file. 

(Beware: this option is implemented in a way which is rather slow; it 

is usually faster to simply rebuild the tags file.) 
-V Produces a list of function names, the filename each function is 

declared in, and the function's line number. This list prints on the 

standard output, and no tags file is created, 
-w Suppresses warning diagnostics. 

The tag main is treated specially in C programs. The tag formed is created 
by prefixing M to the name of the file, with a trailing .c removed, if any, 
and leading path name components also removed. This makes use of ctags 
practical in directories with more than one program. 

FILES 

tags Output tags file 

SEE ALSO 

ex(l), vi(l) in the User's/System Administrator's Reference Manual. 

CREDIT 

This utility was developed at the University of California at Berkeley and is 
used with permission. 
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NAME 

ctrace - C program debugger 

SYNOPSIS 

ctrace [options] [file] 

DESCRIPTION 

The ctrace command allows you to follow the execution of a C program, 
statement-by-statement. The effect is similar to executing a shell procedure 
with the -X option. The ctrace command reads the C program in file (or 
from standard input if you do not specify file), inserts statements to print 
the text of each executable statement and the values of all variables refer- 
enced or modified, and writes the modified program to the standard output. 
You must put the output of ctrace into a temporary file because the cc(l) 
command does not allow the use of a pipe. You then compile and execute 
this file. 

As each statement in the program executes it will be listed at the terminal, 
followed by the name and value of any variables referenced or modified in 
the statement, followed by any output from the statement. Loops in the 
trace output are detected and tracing is stopped until the loop is exited or a 
different sequence of statements within the loop is executed. A warning 
message is printed every 1000 times through the loop to help you detect 
infinite loops. The trace output goes to the standard output so you can put 
it into a fUe for examination with an editor or the hfs{l) or tail{l) com- 
mands. 

The options commonly used are: 

-f functions Trace only these functions. 
-V functions Trace all but these functions. 

You may want to add to the default formats for printing variables. Long 
and pointer variables are always printed as signed integers. Pointers to 
character arrays are also printed as strings if appropriate. Char, short, and 
int variables are also printed as signed integers and, if appropriate, as char- 
acters. Double variables are printed as floating point numbers in scientific 
notation. You can request that variables be printed in additional formats, if 
appropriate, with these options: 

-o Octal 

-X Hexadecimal 

-u Unsigned 

-e Floating point 

These options are used only in special circumstances: 

-1 n Check n consecutively executed statements for looping trace output, 
instead of the default of 20. Use to get all the trace output from 
loops. 

-s Suppress redundant trace output from simple assignment statements 
and string copy function calls. This option can hide a bug caused 
by use of the = operator in place of the == operator. 

-t n Trace n variables per statement instead of the default of 10 (the 
maximum number is 20). The Diagnostics section explains when to 
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use this option. 

-P Run the C preprocessor on the input before tracing it. You can also 
use the -D, -I, and -U cpp(l) options. 

These options are used to tailor the run-time trace package when the traced 
program will run in a non-UNIX System environment: 

-b Use only basic functions in the trace code, that is, those in 
ctype{3Q\ printf{3S), and string(3C). These are usually available 
even in cross-compilers for microprocessors. In particular, this 
option is needed when the traced program runs under an operating 
system that does not have signal(2), fflush{3S\ longjmp(3C), or 
setjmp(3C). 

-p string 

Change the trace print function from the default of 'printf('. For 
example, 'fprintf(stderr,' would send the trace to the standard error 
output. 

-r / Use file / in place of the runtime.c trace function package. This lets 
you change the entire print function, instead of just the name and 
leading arguments (see the -p option). 

EXAMPLE 

If the file Ic.c contains this C program: 

1 #include <stdio.h> 

2 main() /* count lines in input */ 
3{ 

4 int c, nl; 
5 

6 nl = 0; 

7 while ((c = getchar()) != EOF) 

8 if (c = '\n') 

9 ++nl; 

10 printf("%d\n", nl); 
11} 

and you enter these commands and test data: 

cc Ic.c 

a.out 

1 

(cntl-d) 

the program will be compiled and executed. The output of the program will 
be the number 2, which is not correct because there is only one line in the 
test data. The error in this program is common, but subtle. If you invoke 
ctrace with these commands: 

ctrace Ic.c >temp.c 
cc temp.c 
a.out 
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the output will be: 

2 main() 

6 nl = 0; 

/* nl == V 

7 while ({c = getchar()) != EOF) 

The program is now waiting for input. If you enter the same test data as 
before, the output will be: 

/* c == 49 or T V 

8 if (c = '\n') 

/* c == 10 or '\n' */ 

9 ++nl; 

/* nl == 1 V 

7 while ((c = getchar()) != EOF) 
/* c == 10 or '\n' V 

8 if (c = '\n') 

/* c == 10 or '\n' */ 

9 ++nl; 

/* nl == 2 */ 
7 while ((c = getchar()) != EOF) 

If you now enter an end-of-file character (cntl-d) the final output will be: 

/* c == -1 V 

10 printf("%d\n", nl); 
/* nl == 2 */2 
return 

Note that the program output printed at the end of the trace line for the nl 
variable. Also note the return comment added by ctrace at the end of the 
trace output. This shows the implicit return at the terminating brace in the 
function. 

The trace output shows that variable c is assigned the value '1' in line 7, but 
in line 8 it has the value '\n'. Once your attention is drawn to this if state- 
ment, you will probably realize that you used the assignment operator (=) 
in place of the equality operator (==). You can easily miss this error during 
code reading. 

EXECUTION-TIME TRACE CONTROL 

The default operation for ctrace is to trace the entire program file, unless 
you use the -f or -v options to trace specific functions. This does not give 
you statement-by-statement control of the tracing, nor does it let you turn 
the tracing off and on when executing the traced program. 

You can do both of these by adding ctroffQ and ctroni) function calls to 
your program to turn the tracing off and on, respectively, at execution time. 
Thus, you can code arbitrarily complex criteria for trace control with if state- 
ments, and you can even conditionally include this code because ctrace 
defines the CTRACE preprocessor variable. For example: 
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#ifdef CTRACE 

if (c == && i > 1000) 
ctron(); 

#endif 

You can also call these functions from sdb{l) if you compile with the -g 
option. For example, to trace all but lines 7 to 10 in the main function, 
enter: 

sdb a.out 
main: 7b ctroff() 
main: lib ctronQ 
r 

You can also turn the trace off and on by setting static variable tr_ct_ to 
and 1, respectively. This is useful if you are using a debugger that cannot 
call these functions directly. 

FILES 

/usr/lib/ctrace/runtime.c run-time trace package 

SEE ALSO 

signal(2), ctype(3C), fclose(3S), printf(3S), setjmp(3C), string(3C). 
bfs(l), tail(l) in the User's /System Administrator's Reference Manual. 
DIAGNOSTICS 

This section contains diagnostic messages from both ctrace and cc(l), since 
the traced code often gets some cc warning messages. You can get cc error 
messages in some rare cases, all of which can be avoided. 

ctrace Diagnostics 

warning: some variables are not traced in this statement 

Only 10 variables are traced in a statement to prevent the C com- 
piler "out of tree space; simplify expression" error. Use the -t 
option to increase this number. 

warning: statement too long to trace 

This statement is over 400 characters long. Make sure that you are 
using tabs to indent your code, not spaces. 

cannot handle preprocessor code, use -P option 

This is usually caused by #ifdef/#endif preprocessor statements in 
the middle of a C statement, or by a semicolon at the end of a 
#define preprocessor statement. 

Hf ... else if sequence too long 

Split the sequence by removing an else from the middle. 
possible syntax error, try -P option 

Use the -P option to preprocess the ctrace input, along with any 
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appropriate -D, -I, and -U preprocessor options. If you still get the 
error message, check the WARNINGS section below. 

Cc Diagnostics 

warning: illegal combination of pointer and integer 
warning: statement not reached 
warning: sizeof returns 

Ignore these messages. 

compiler takes size of function 

See the ctrace "possible syntax error" message above. 

yacc stack overflow 

See the ctrace "'if ... else if' sequence too long" message above. 

out of tree space; simplify expression 

Use the -t option to reduce the number of traced variables per state- 
ment from the default of 10. Ignore the "ctrace: too many variables 
to trace" warnings you will now get. 

redeclaration of signal 

Either correct this declaration of signal{2), or remove it and #include 
<signal.h>. 

WARNINGS 

You will get a ctrace syntax error if you omit the semicolon at the end of 
the last element declaration in a structure or union, just before the right 
brace (}). This is optional in some C compilers. 

Defining a function with the same name as a system function may cause a 
syntax error if the number of arguments is changed. Just use a different 
name. 

The ctrace command assumes that BADMAG is a preprocessor macro, and 
that EOF and NULL are #defined constants. Declaring any of these to be 
variables, e.g., " int EOF; " , will cause a syntax error. 

BUGS 

The ctrace command does not know about the components of aggregates 
like structures, unions, and arrays. It cannot choose a format to print all the 
components of an aggregate when an assignment is made to the entire 
aggregate, ctrace may choose to print the address of an aggregate or use the 
wrong format (e.g., 3.149050e-311 for a structure with two integer 
members) when printing the value of an aggregate. 

Pointer values are always treated as pointers to character strings. 

The loop trace output elimination is done separately for each file of a multi- 
file program. This can result in functions called from a loop still being 
traced, or the elimination of trace output from one function in a file until 
another in the same file is called. 
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NAME 

cxref - generate C program cross-reference 

SYNOPSIS 

cxref [ options ] files 

DESCRIPTION 

The cxref command analyzes a collection of C files and attempts to build a 
cross-reference table. The cxref command uses a special version of cpp to 
include #define'd information in its symbol table. It produces a listing on 
standard output of all symbols (auto, static, and global) in each file 
separately, or, vnth the -c option, in combination. Each symbol contains an 
asterisk (*) before the declaring reference. 

In addition to the -D, -I, and -U options [vy^hich are interpreted just as they 
are by cc(l) and cpp{l)l the following options are interpreted by cxref: 

-c Print a combined cross-reference of all input files. 

-w<n«m> 

Width option vy^hich formats output no vdder than <num> 
(decimal) columns. This option will default to 80 if <num> is not 
specified or is less than 51. 

-o file Direct output to file. 

-s Operate silently; do not print input file names, 
-t Format listing for 80-column vs^idth. 

FILES 

LLIBDIR usually /usr/lib 

LLIBDIR/xcpp special version of the C preprocessor. 

SEE ALSO 

cc(l), cpp(l). 

DIAGNOSTICS 

Error messages are unusually cryptic, but usually mean that you cannot 
compile these files. 

BUGS 

The cxref command considers a formal argument in a Mefine macro defini- 
tion to be a declaration of that symbol. For example, a program that 
if'includes ctype.h, will contain many declarations of the variable c. 
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NAME 

delta - make a delta (change) to an SCCS file 
SYNOPSIS 

delta [-rSID] [-s] [-n] [-glist] [-m[mrlist]] [-y[comment]] [-p] files 
DESCRIPTION 

The delta command is used to permanently introduce into the named SCCS 
file changes that were made to the file retrieved by get{l) (called the g-file, 
or generated file). 

The delta command makes a delta to each named SCCS file. If a directory is 
named, delta behaves as though each file in the directory were specified as 
a named file, except that non-SCCS files (last component of the path name 
does not begin with s.) and unreadable files are silently ignored. If a name 
of - is given, the standard input is read (see WARNINGS); each line of the 
standard input is taken to be the name of an SCCS file to be processed. 

The delta command may issue prompts on the standard output depending 
upon certain keyletters specified and flags [see admin{l)] that may be 
present in the SCCS file (see -m and -y keyletters below). 

Keyletter arguments apply independently to each named file. 

-rSID Uniquely identifies which delta is to be made to the 

SCCS file. The use of this keyletter is necessary only 
if two or more outstanding gets for editing (get -e) on 
the same SCCS file were done by the same person 
(login name). The SID value specified with the -r 
keyletter can be either the SID specified on the get 
command line or the SID to be made as reported by 
the get command [see get{l)], A diagnostic results if 
the specified SID is ambiguous or if a required SID is 
omitted on the command line. 

Suppresses the issue, on the standard output, of the 
created delta's SID, as well as the number of lines 
inserted, deleted, and unchanged in the SCCS file. 

Specifies retention of the edited g-file (normally 
removed at completion of delta processing). 

a list [see get{l) for the definition of list] of deltas 
which are to be ignored when the file is accessed at 
the change level (SID) created by this delta. 

If the SCCS file has the v flag set [see admin{l)], then 
a Modification Request (MR) number must be supplied 
as the reason for creating the new delta. 

If -m is not used and the standard input is a terminal, 
the prompt MRs? is issued on the standard output 
before the standard input is read; if the standard input 
is not a terminal, no prompt is issued. The MRs? 
prompt always precedes the comments? prompt (see 
-y keyletter). 



-n 



-glist 
-m[mr/fs^] 
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MRS in a list are separated by blanks and/or tab char- 
acters. An unescaped new-line character terminates 
the MR list. 

Note that if the v flag has a value [see admin{l)], it is 
taken to be the name of a program (or shell pro- 
cedure) which will validate the correctness of the MR 
numbers. If a non-zero exit status is returned from 
the MR number validation program, delta terminates. 
(It is assumed that the MR numbers were not all 
valid.) 

-y[comment] Arbitrary text used to describe the reason for making 
the delta. A null string is considered a valid comment. 

If -y is not specified and the standard input is a ter- 
minal, the prompt comments? is issued on the stand- 
ard output before the standard input is read; if the 
standard input is not a terminal, no prompt is issued. 
An unescaped new-line character terminates the com- 
ment text. 

Causes delta to print (on the standard output) the 
sees file differences before and after the delta is 
applied in a diff{l) format. 



Existed before the execution of delta; removed after com- 
pletion of delta. 

Existed before the execution of delta; may exist after com- 
pletion of delta. 

Created during the execution of delta; removed after com- 
pletion of delta. 

Created during the execution of delta; renamed to SCCS file 
after completion of delta. 

Created during the execution of delta; removed during the 
execution of delta. 

Created during the execution of delta; removed after com- 
pletion of delta. 

/usr/bin/bdiff Program to compute differences between the "gotten" file 
and the g-file. 

SEE ALSO 

admin(l), cdc(l), get(l), prs(l), rmdel(l), sccsfile(4). 
bdiff(l), in the User's/System Administrator's Reference Manual. 
WARNINGS 

Lines beginning with an SOH ASCII character (binary 001) cannot be placed 
in the SCCS file unless the SOH is escaped. This character has special mean- 
ing to SCCS [see sccsfile{4)] and will cause an error. 

A get of many SCCS files, followed by a delta of those files, should be 
avoided when the get generates a large amount of data. Instead, multiple 
get /delta sequences should be used. 



FILES 

g-file 
p-file 
q-file 
x-file 
z-file 
d-file 
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If the standard input {-) is specified on the delta command line, the -m (if 
necessary) and -y keyletters must also be present. Omission of these 
keyletters causes an error to occur. 

Comments are limited to text strings of at most 512 characters. 
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NAME 

dis - object code disassembler 
SYNOPSIS 

dis [-0] [-V] [-L] [-S] [-d sec] [-da sec ] [-F function ] [-t sec] [-1 string] 
file ... 

DESCRIPTION 

The dis command produces an assembly language listing of file, which may 
be an object file or an archive of object files. The listing includes assembly 
statements and an octal or hexadecimal representation of the binary that 
produced those statements. 

The following options are interpreted by the disassembler and may be speci- 
fied in any order. 

-o Print numbers in octal. The default is hexadecimal. 

-V Print, on standard error, the version number of the disassem- 

bler being executed. 

-L Look up source labels in the symbol table for subsequent 

printing. This option works only if the file was compiled with 
additional debugging information [e.g., the -g option of cc(l)]. 

-s Perform symbolic disassembly, i.e., specify source symbol 

names for operands where possible. Symbolic disassembly out- 
put will appear on the line following the instruction. For maxi- 
mal symbolic disassembly to be performed, the file must be 
compUed with additional debugging information [e.g., the -g 
option of cc(l)]. Symbol names will be printed using C syn- 
tax. 

-d sec Disassemble the named section as data, printing the offset of 

the data from the beginning of the section. 

-da sec Disassemble the named section as data, printing the actual 
address of the data. 

-F function Disassemble only the named function in each object file speci- 
fied on the command line. The -F option may be specified 
multiple times on the command line. 

-t sec Disassemble the named section as text. 

-1 string Disassemble the library file specified by string. For example, 
one would issue the command dis -1 x -1 z to disassemble 
libx.a and libz.a. All libraries are assumed to be in LIBDIR. 

If the -d, -da or -t options are specified, only those named sections from 
each user-supplied file name will be disassembled. Otherwise, all sections 
containing text will be disassembled. 

On output, a number enclosed in brackets at the beginning of a line, such as 
[5], represents that the break-pointable line number starts with the following 
instruction. These line numbers will be printed only if the file was com- 
piled with additional debugging information [e.g., the -g option of cc(l)]. 
An expression such as <40> in the operand field or in the symbolic 
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disassembly, following a relative displacement for control transfer instruc- 
tions, is the computed address within the section to which control will be 
transferred. A function name will appear in the first column, followed by 
0. 

FILES 

LIBDIR usually /lib. 

SEE ALSO 

as(l), cc(l), ld(l), a.out(4). 

DIAGNOSTICS 

The self-explanatory diagnostics indicate errors in the command line or 
problems encountered with the specified files. 
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NAME 

dump - dump selected parts of an object file 

SYNOPSIS 

dump [ options ] files 

DESCRIPTION 

The dump command dumps selected parts of each of its object file argu- 
ments. 

This command will accept both object files and archives of object files. It 
processes each file argument according to one or more of the following 
options: 

-a Dump the archive header of each member of each archive file 

argument. 

-g Dump the global symbols in the symbol table of an archive. 

-f Dump each file header. 

-o Dump each optional header. 

-h Dump section headers. 

-s Dump section contents. 

-r Dump relocation information. 

-1 Dump line number information. 

-t Dump symbol table entries. 

-z name Dump line number entries for the named function, 
-c Dump the string table. 

-L Interpret and print the contents of the .lib sections. 

The following modifiers are used in conjunction with the options listed 
above to modify their capabilities. 

-d number Dump the section number, number, or the range of sections 
starting at number and ending at the number specified by +d. 

+d number Dump sections in the range either beginning with first section 
or beginning with section specified by -d. 

-n name Dump information pertaining only to the named entity. This 
modifier applies to -h, -s, -r, -1, and -t. 

-p Suppress printing of the headers. 

-t index Dump only the indexed symbol table entry. The -t used in 
conjunction with +t, specifies a range of symbol table entries. 

H-t index Dump the symbol table entries in the range ending with the 
indexed entry. The range begins at the first symbol table entry 
or at the entry specified by the -t option. 

-u Underline the name of the file for emphasis. 
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-V Dump information in symbolic representation rather than 

numeric (e.g., C-_STATIC instead of 0X02). This modifier can be 
used with all the above options except -s and -o options of 
dump. 

-z name,number 

Dump line number entry or range of line numbers starting at 
number for the named function. 

+z number Dump line numbers starting at either function name or number 
specified by -z, up to number specified by +z. 

Blanks separating an option and its modifier are optional. The comma 
separating the name from the number modifying the -z option may be 
replaced by a blank. 

The dump command attempts to format the information it dumps in a 
meaningful way, printing certain information in character, hex, octal, or 
decimal representation as appropriate. 

SEE ALSO 

a.out(4), ar(4). 
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NAME 

gencc - create a front-end to the cc command 

SYNOPSIS 

gencc 

DESCRIPTION 

The gencc command is an interactive command designed to aid in the crea- 
tion of a front-end to the cc command. Since hard-coded path names have 
been eliminated from the C Compilation System (CCS), it is possible to 
move pieces of the CCS to new locations without recompiling the CCS. 
The new locations of moved pieces can be specified through the -Y option 
to the cc command. However, it is inconvenient to supply the proper -Y 
options with every invocation of the cc command. Further, if a system 
administrator moves pieces of the CCS, such movement should be invisible 
to users. 

The front-end to the cc command which gencc generates is a one-line shell 
script which calls the cc command with the proper -Y options specified. 
The front-end to the cc command will also pass all user supplied options to 
the cc command. 

The gencc command prompts for the location of each tool and directory 
which can be respecified by a -Y option to the cc command. If no location 
is specified, it assumes that that piece of the CCS has not been relocated. 
After all the locations have been prompted for, gencc will create the front- 
end to the cc command. 

The gencc command creates the front-end to the cc command in the current 
working directory and gives the file the same name as the cc command. 
Thus, gencc can not be run in the same directory containing the actual cc 
command. Further, if a system administrator has redistributed the CCS, the 
actual cc command should be placed somewhere which is not typically in a 
user's PATH (e.g., /lib). This will prevent users from accidentally invoking 
the cc command without using the front-end. 

HLES 

./cc front-end to cc 

SEE ALSO 

cc(l). 

CAVEATS 

The gencc command does not produce any warnings if a tool or directory 
does not exist at the specified location. Also, gencc does not actually move 
any files to new locations. 
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NAME 

get - get a version of an SCCS file 
SYNOPSIS 

get [-rSID] [-ccutoff] [-ilist] [-xlist] [-wstring] [-aseq-no.] [-k] [-e] [-l[p] 
[-p] [-m] [-n] [-8] [-b] [-g] [-t] file ... 

DESCRIPTION 

The get command generates an ASCII text file from each named SCCS file 
according to the specifications given by its keyletter arguments, which begin 
with -. The arguments may be specified in any order, but all keyletter 
arguments apply to all named SCCS files. If a directory is named, get 
behaves as though each file in the directory were specified as a named file, 
except that non-SCCS files (last component of the path name does not begin 
with s.) and unreadable files are silently ignored. If a name of - is given, 
the standard input is read; each line of the standard input is taken to be the 
name of an SCCS file to be processed. Again, non-SCCS files and unread- 
able files are silently ignored. 

The generated text is normally written into a file called the g-file whose 
name is derived from the SCCS file name by simply removing the leading s.; 
(see also FILES, below). 

Each of the keyletter arguments is explained below as though only one 
SCCS file is to be processed, but the effects of any keyletter argument 
applies independently to each named file. 

-rSID The SCCS /Dentification string (SID) of the version (delta) of 
an SCCS file to be retrieved. Table 1 below shows, for the 
most useful cases, what version of an SCCS file is retrieved 
[as well as the SID of the version to be eventually created 
by delta(l) if the -e keyletter is also used], as a function of 
the SID specified. 

-ccutoff Cutoff date-time, in the form: 

YY[MM[DD[HH[MM[SS]]]]] 

No changes (deltas) to the SCCS file which were created 
after the specified cutoff date-time are included in the gen- 
erated ASCII text file. Units omitted from the date-time 
default to their maximum possible values; that is, -c7502 is 
equivalent to -c750228235959. Any number of non-numeric 
characters may separate the various 2-digit pieces of the 
cutoff date-time. This feature allows one to specify a cutoff 
date in the form: "-c77/2/2 9:22:25". Note that this 
implies that one may use the %E% and %U% identification 
keywords (see below) for nested gets. 

get "-c%E% %U%" s.file 
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-i/fsf A list of deltas to be included (forced to be applied) in the 
creation of the generated file. The list has the following 
syntax: 

<list> ::= <range> I <list> , <range> 
<range> ::= SID I SID - SID 

SID, the sees Identification of a delta, may be in any form 
shown in the "SID Specified" column of Table 1. 

-xlist A list of deltas to be excluded in the creation of the gen- 
erated file. See the -i keyletter for the list format. 

-e Indicates that the get is for the purpose of editing or mak- 

ing a change (delta) to the SCCS file via a subsequent use of 
delta(l). The -e keyletter used in a get for a particular ver- 
sion (SID) of the SCCS file prevents further gets for editing 
on the same SID until delta is executed or the j (joint edit) 
flag is set in the SCCS file [see admin{l)]. Concurrent use of 
get -e for different SIDs is always allowed. 

If the g'file generated by get with an -e keyletter is 
accidentally ruined in the process of editing it, it may be 
regenerated by re-executing the get command with the -k 
keyletter in place of the -e keyletter. 

SCCS file protection specified via the ceiling, floor, and 
authorized user list stored in the SCCS file [see admin{l)] is 
enforced when the -e keyletter is used. 

-b Used with the -e keyletter to indicate that the new delta 

should have an SID in a new branch as shown in Table 1. 
This keyletter is ignored if the b flag is not present in the 
file [see admin{l)] or if the retrieved delta is not a leaf delta. 
(A leaf delta is one that has no successors on the SCCS file 
tree.) 

Note: A branch delta may always be created from a non- 
leaf delta. Partial SIDs are interpreted as shown in the "SID 
Retrieved" column of Table 1. 

-k Suppresses replacement of identification keywords (see 

below) in the retrieved text by their value. The -k keyletter 
is implied by the -e keyletter. 

-l[p] Causes a delta summary to be written into an l-file. If -Ip 
is used, then an l-file is not created; the delta summary is 
written on the standard output instead. See FILES for the 
format of the l-file. 

-p Causes the text retrieved from the SCCS file to be written 

on the standard output. No g-file is created. All output 
which normally goes to the standard output goes to file 
descriptor 2 instead, unless the -s keyletter is used, in 
which case it disappears. 
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-s Suppresses all output normally written on the standard out- 

put. However, fatal error messages (which always go to file 
descriptor 2) remain unaffected. 

-m Causes each text line retrieved from the SCCS file to be pre- 

ceded by the SID of the delta that inserted the text line in 
the SCCS file. The format is: SID, followed by a horizontal 
tab, followed by the text line. 

-n Causes each generated text line to be preceded with the 

%M% identification keyword value (see below). The for- 
mat is: %M% value, followed by a horizontal tab, followed 
by the text line. When both the -m and -n keyletters are 
used, the format is: %M% value, followed by a horizontal 
tab, followed by the -m keyletter generated format. 

-g Suppresses the actual retrieval of text from the SCCS file. It 

is primarily used to generate an l-file, or to verify the 
existence of a particular SID. 

-t Used to access the most recently created delta in a given 

release (e.g., -rl), or release and level (e.g., -rl.2). 

-w string Substitute string for all occurrences of %W% when getting 
the file. 

~aseq-no. The delta sequence number of the SCCS file delta (version) 
to be retrieved [see sccsfile{5)]. This keyletter is used by the 
comb{l) command; it is not a generally useful keyletter. If 
both the -r and -a keyletters are specified, only the -a 
keyletter is used. Care should be taken when using the -a 
keyletter in conjunction with the -e keyletter, as the SID of 
the delta to be created may not be what one expects. The 
-r keyletter can be used with the -a and -e keyletters to 
control the naming of the SID of the delta to be created. 

For each file processed, get responds (on the standard output) vdth the SID 
being accessed and with the number of lines retrieved from the SCCS file. 

If the -e keyletter is used, the SID of the delta to be made appears after the 
SID accessed and before the number of lines generated. If there is more 
than one named file or if a directory or standard input is named, each file 
name is printed (preceded by a new-line) before it is processed. If the -i 
keyletter is used, included deltas are listed following the notation 
"Included"; if the -x keyletter is used, excluded deltas are listed following 
the notation "Excluded". 
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TABLE 1. Determination of SCCS Identification String 



SID* 
Specified 


-b Keyletter 
Usedt 


Other 
Conditions 


SID 
Retrieved 


SID of Delta 
to be Created 


nonet 


no 


R defaults to mR 


mR.mL 


mR.(mL+l) 


nonej 


yes 


R defaults to mR 


mR.mL 


mR.mL.(mB+l).l 


R 


no 


R > mR 


mR.mL 


R.l*** 


R 


no 


R = mR 


mR tnT 


mR (mJ 


R 


yes 


R > mR 


mR.mL 


mR.mL.(mB+l).l 


R 


ves 


R = mR 


mR.mL 


mR.mL.(mB+l).l 


R 




R < mR and 
R does not exist 


hR.mL** 


hR.mL.(mBH-l).l 






Trunk succ.# 






R 


- 


in release > R 
and R exists 


R.mL 


R.mL.(mB+l).l 


15 T 

K.L 


no 


No trunk succ. 


R.L 


R.(L+1) 


R.L 


ves 


No trunk succ. 


R.L 


R.L.(mB+l).l 


R.L 




Trunk succ. 
in release > R 


R.L 


R.L.(mB+l).l 


R.L.B 


no 


No branch succ. 


R.L.B.mS 


R.L.B.(mS+l) 


R.L.B 


yes 


No branch succ. 


R.L.B.mS 


R.L.(mB+l).l 


R.L.B.S 


no 


No branch succ. 


R.L.B.S 


R.L.B.(S+1) 


R.L.B.S 


ves 


No branch succ. 


R.L.B.S 


R.L.(mB+l).l 


R.L.B.S 




Branch succ. 


R.L.B.S 


R.L.(mB+l).l 



"R", "L", "B", and "S" are the "release", "level", "branch", and 
"sequence" components of the SID, respectively; "m" means "max- 
imum". Thus, for example, "R.mL" means "the maximum level 
number within release R"; "R.L.(mB-l-l).l" means "the first sequence 
number on the new branch (i.e., maximum branch number plus one) of 
level L within release R". Note that if the SID specified is of the form 
"R.L", "R.L.B", or "R.L.B.S", each of the specified components must 
exist. 

"hR" is the highest existing release that is lower than the specified, 
nonexistent, release R. 

This is used to force creation of the first delta in a new release. 



# Successor. 

t The -b keyletter is effective only if the b flag [see admin{l)] is present 

in the file. An entry of - means "irrelevant". 
J This case applies if the d (default SID) flag is not present in the file. If 

the d flag is present in the file, then the SID obtained from the d flag is 



interpreted as if it had been specified on the command line. Thus, one 
of the other cases in this table applies. 
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IDENTIFICATION KEYWORDS 

Identifying information is inserted into the text retrieved from the SCCS file 
by replacing identification keywords with their value wherever they occur. 
The following keywords may be used in the text stored in an SCCS file: 

Keyword Value 

%MVo Module name: either the value of the m flag in the file [see 
flrfmm(l)], or if absent, the name of the SCCS file with the lead- 
ing s. removed. 

%I% SCCS identification (SID) (%R%.%L%.%B%.%S%) of the 

retrieved text. 
%R% Release. 
%L% Level. 
VoBVo Branch. 
%S% Sequence. 
VoDVo Current date (YY/MM/DD). 
%H% Current date (MM/DD/YY). 
%T% Current time (HH:MM:SS). 

%E% Date newest applied delta was created (YY/MM/DD). 

%G% Date newest applied delta was created (MM/DD/YY). 

%U% Time newest applied delta was created (HH:MM:SS). 

%Y% Module type: value of the t flag in the SCCS file [see admin(l)]. 

%F% SCCS file name. 

%P% Fully qualified SCCS file name. 

%Q% The value of the q flag in the file [see admin{l)]. 

%C% Current line number. This keyword is intended for identifying 

messages output by the program such as "this should not have 

happened" type errors. It is not intended to be used on every 

line to provide sequence numbers. 
VoZVo The 4-character string @(#) recognizable by what{l). 
%W% A shorthand notation for constructing what{l) strings for UNIX 

system program files. %W% = %Z%%M%<horizontal- 

tab>%I% 

%A% Another shorthand notation for constructing what{l) strings for 
non-UNIX system program files. 
%A% = %Z%%Y% %M% %I%%Z% 

Several auxiliary files may be created by get. These files are known generi- 
cally as the g-file, l-file, p-file, and z-file. The letter before the hyphen is 
called the tag. An auxiliary file name is formed from the SCCS file name: 
the last component of all SCCS file names must be of the form s.module- 
name; the auxiliary files are named by replacing the leading s with the tag. 
The g-file is an exception to this scheme: the g-file is named by removing 
the s. prefix. For example, s.xyz.c, the auxiliary file names would be xyz.c, 
l.xyz.c, p.xyz.c, and z.xyz.c, respectively. 

The g-file, which contains the generated text, is created in the current direc- 
tory (unless the -p keyletter is used). A g-file is created in all cases, 
whether or not any lines of text were generated by the get. 
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It is owned by the real user. If the -k keyletter is used or implied, its mode 
is 644; otherwise its mode is 444. Only the real user needs write permission 
in the current directory. 

The l-file contains a table showing which deltas were applied in generating 
the retrieved text. The l-file is created in the current directory if the -1 
keyletter is used; its mode is 444 and it is owned by the real user. Only the 
real user needs write permission in the current directory. 

Lines in the l-file have the following format: 

a. A blank character if the delta was applied; 

* otherwise. 

b. A blank character if the delta was applied or was not 
applied and ignored; 

* if the delta was not applied and was not ignored. 

c. A code indicating a "special" reason why the delta was or 
was not applied: 

"I": Included. 
"X": Excluded. 

"C": Cut off (by a -c keyletter). 

d. Blank. 

e. sees identification (SID). 

f. Tab character. 

g. Date and time (in the form YY/MM/DD HH:MM:SS) of crea- 
tion. 

h. Blank. 

i. Login name of person who created delta. 

The comments and MR data follow on subsequent lines, indented 
one horizontal tab character. A blank line terminates each entry. 

The p-file is used to pass information resulting from a get with a -e 
keyletter along to delta. Its contents are also used to prevent a subsequent 
execution of get with a -e keyletter for the same SID until delta is executed 
or the joint edit flag, j, [see admin{l)] is set in the SCCS file. The p-file is 
created in the directory containing the SCCS file and the effective user must 
have write permission in that directory. Its mode is 644 and it is owned by 
the effective user. The format of the p-file is: the gotten SID, followed by a 
blank, followed by the SID that the new delta will have when it is made, 
followed by a blank, followed by the login name of the real user, followed 
by a blank, followed by the date-time the get was executed, followed by a 
blank and the -i keyletter argument if it was present, followed by a blank 
and the -x keyletter argument if it was present, followed by a new-line. 
There can be an arbitrary number of lines in the p-file at any time; no two 
lines can have the same new delta SID. 

The z-file serves as a lock-out mechanism against simultaneous updates. Its 
contents are the binary (2 bytes) process ID of the command (i.e., get) that 
created it. The z-file is created in the directory containing the SCCS file for 
the duration of get. The same protection restrictions as those for the p-file 
apply for the z-file. The z-file is created mode 444. 
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FILES 

g-file Existed before the execution of delta; removed after com- 

pletion of delta . 

p-file Existed before the execution of delta; may exist after com- 

pletion of delta . 

q-file Created during the execution of delta; removed after com- 

pletion of delta . 

x-file Created during the execution of delta; renamed to SCCS file 

after completion of delta. 
z-file Created during the execution of delta; removed during the 

execution of delta. 

d-file Created during the execution of delta; removed after com- 

pletion of delta. 

/usr/bin/bdiff Program to compute differences between the "gotten" file 
and the g-file. 

SEE ALSO 

admin(l), delta(l), prs(l), what(l). 

BUGS 

If the effective user has write permission (either explicitly or implicitly) in 
the directory containing the SCCS files, but the real user does not, then only 
one file may be named when the -e keyletter is used. 
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NAME 

hdr - display selected parts of a XENIX object file 

SYNOPSIS 

hdr [ -dhmprsSt ] file ... 

DESCRIPTION 

hdr displays XENIX object file headers, symbol tables, and text or data relo- 
cation records in ASCII formats. It also prints out seek positions for the vari- 
ous segments in the object file. A.out, x.out, and x.out segmented formats 
and archives are understood. 

The symbol table format consists of six fields. In a.out formats the third 
field is missing. The first field is the symbol's index or position in the sym- 
bol table, printed in decimal. The index of the first entry is zero. The 
second field is the type, printed in hexadecimal. The third field is the s_seg 
field, printed in hexadecimal. The fourth field is the symbol's value in hex- 
adecimal. The fifth field is a single character that represents the symbol's 
type as in nm (CP), except C common is not recognized as a special case of 
undefined. The last field is the symbol name. 

If long form relocation is present, the format consists of six fields. The first 
is the descriptor, printed in hexadecimal. The second is the symbol ID or 
index, in decimal. This field is used for external relocations as an index into 
the symbol table. It should reference an undefined symbol table entry. The 
third field is the position, or offset, within the current segment at which 
relocation is to take place; it is printed in hexadecimal. The fourth field is 
the name of the segment referenced in the relocation: text, data, bss, or 
EXT for external. The fifth field is the size of relocation: byte, word (2 
bytes), or long. The last field will indicate, if present, that the relocation is 
relative. 

If short form relocation is present, the format consist of three fields. The 
first field is the relocation command in hexadecimal. The second field con- 
tains the name of the segment referenced: text or data. The last field indi- 
cates the size of relocation: word or long. 

The hdr options are: 

-d Prints the data relocation records. 

-h Prints the object file header and extended header. Each field in the 
header or extended header is labeled. This is the default option. 

-m Prints the text and data segments. This option is similar to the -S 
option but only for text and data segments. 

-p Prints the seek positions as defined by macros in the include file 
<a.out.h>. 

-r Prints both text and data relocation records, 
-s Prints the symbol table. 

-S Prints the file segment table with a header. (Only applicable to 
x.out segmented executable files.) 
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-t Prints the text relocation records. 

SEE ALSO 

a.out(4), nm(l). 

NOTES 

hdr is only for use with object files created under XENIX. 
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NAME 

i286emul - emulate 80286 

SYNOPSIS 

i286emul [ arg ... ] prog286 

DESCRIPTION 

llSSemul is an emulator that allows programs from UNIX System V Release 
2 or Release 3 on the Intel 80286 to run on UNIX System V Release 3 on 
the Intel 80386. 

The UNIX system recognizes an attempt to exec (2) a 286 program, and 
automatically exec's the 286 emulator with the 286 program name as an 
additional argument. It is not necessary to specify the ilSSemul emulator on 
the command line. The 286 programs can be invoked using the same com- 
mand format as on the 286 UNIX System V. 

I286emul reads the 286 program's text and data into memory and maps 
them through the LDT [via sysi86{2)] as 286 text and data segments. It also 
sets callgate 89 in the GDT (which is used by 286 programs for system 
calls) to point to a routine in i286emul. I286emul starts the 286 program by 
jumping to its entry point. 

When the 286 program attempts to do a system call, i286emul takes control. 
It does any conversions needed between the 286 system call and the 
equivalent 386 system call, and performs the 386 system call. The results 
are converted to the form the 286 program expects, and the 286 program is 
resumed. 

The following are some of the differences between a program running on a 
286 and a 286 program using i286emul on a 386: 

A 286 program under i286emul always has 64k in the stack segment 
if it is a large-model process, or 64k in the data segment if it is a 
small-model process. 

System calls and signal handling use more space on the stack under 
i286emul than it does on a 286. 

Attempts to unlink or write on the 286 program will fail on the 286 
with ETXTBSY. Under i286emul, they will not fail. 

Ptrace{2) is not supported under i286emul. 

The 286 program must be readable for the emulator to read it. 

FILES 

/bin/i286emul 

The emulator must have this name and be in /bin if it is to be 
automatically invoked when exec (2) is used on a 286 program. 

BUGS 

The signal mechanism under the emulator is the System V release 2 signal 
mechanism rather than the System V release 3 mechanism. 
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NAME 

infocmp - compare or print out terminfo descriptions 
SYNOPSIS 

infocmp [-d] [-C] [-n] [-1] [-L] [-C] [-r] [-u] [-s dlilllc] [-v] [-V] [-1] [-w 
width] [-A directory] [-B directory] [termname ...] 

DESCRIPTION 

infocmp can be used to compare a binary terminfo (4) entry with other ter- 
minfo entries, rewrite a terminfo (4) description to take advantage of the 
use= terminfo field, or print out a terminfo{4) description from the binary 
file [ferm(4)] in a variety of formats. In all cases, the boolean fields will be 
printed first, followed by the numeric fields, followed by the string fields. 

Default Options 

If no options are specified and zero or one termnames are specified, the -I 
option will be assumed. If more than one termname is specified, the -d 
option will be assumed. 

Comparison Options [-d] [-c] [-n] 

infocmp compares the terminfo (4) description of the first terminal termname 
with each of the descriptions given by the entries for the other terminal's 
termnames. If a capability is defined for only one of the terminals, the value 
returned will depend on the type of the capability: F for boolean variables, 
-1 for integer variables, and NULL for string variables. 

-d produce a list of each capability that is different. In this manner, if 
one has two entries for the same terminal or similar terminals, 
using infocmp will show what is different between the two entries. 
This is sometimes necessary when more than one person produces 
an entry for the same terminal and one wants to see what is dif- 
ferent between the two. 

-c produce a list of each capability that is common between the two 
entries. Capabilities that are not set are ignored. This option can 
be used as a quick check to see if the -u option is worth using. 

-n produce a list of each capability that is in neither entry. If no term- 
names are given, the environment variable TERM will be used for 
both of the termnames. This can be used as a quick check to see if 
anything was left out of the description. 

Source Listing Options [-1] [-L] [-C] [-r] 

The -I, -L, and -C options will produce a source listing for each terminal 
named. 

-I use the terminfo{4) names 

-L use the long C variable name listed in <term.h> 
-C use the termcap names 

-r when using -C, put out all capabilities in termcap form 

If no termnames are given, the environment variable TERM will be used for 
the terminal name. 
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The source produced by the -C option may be used directly as a termcap 
entry, but not all of the parameterized strings may be changed to the 
termcap format, infocmp will attempt to convert most of the parameterized 
information, but that which it doesn't will be plainly marked in the output 
and commented out. These should be edited by hand. 

All padding information for strings will be collected together and placed at 
the beginning of the string where termcap expects it. Mandatory padding 
(padding information with a trailing '/') will become optional. 

All termcap variables no longer supported by terminfo{4), but which are 
derivable from other terminfo{4) variables, will be output. Not all ter- 
minfo{A) capabilities will be translated; only those variables which were part 
of termcap will normally be output. Specifying the -r option will take off 
this restriction, allowing all capabilities to be output in termcap form. 

Note that because padding is collected to the beginning of the capability, 
not all capabilities are output, mandatory padding is not supported, and 
termcap strings were not as flexible, it is not always possible to convert a 
terminfo{4) string capability into an equivalent termcap format. Not all of 
these strings will be able to be converted. A subsequent conversion of the 
termcap file back into terminfo{4) format will not necessarily reproduce the 
original terminfo(A) source. 

Some common terminfo parameter sequences, their termcap equivalents, and 
some terminal types which commonly have such sequences, are: 



Terminfo Termcap Representative Terminals 

%pl%c %. adm 

%pl%d %d hp, ANSI standard, vtlOO 

%pl%'x'%+%c %+x concept 

%i %i ANSI standard, vtlOO 



%pl %?%'x'%>%t%pl %y %+%; %>xy concept 
%p2 is printed before %pl %r hp 

Use= Option [-u] 

-u produce a terminfo{4) source description of the first terminal term- 
name which is relative to the sum of the descriptions given by the 
entries for the other terminals termnames. It does this by analyzing 
the differences between the first termname and the other termnames 
and producing a description with use= fields for the other termi- 
nals. In this manner, it is possible to retrofit generic terminfo 
entries into a terminal's description. Or, if two similar terminals 
exist, but were coded at different times or by different people so 
that each description is a full description, using infocmp will show 
what can be done to change one description to be relative to the 
other. 

A capability will get printed with an at-sign (@) if it no longer exists in the 
first termname, but one of the other termname entries contains a value for it. 
A capability's value gets printed if the value in the first termname is not 
found in any of the other termname entries, or if the first of the other 
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termname entries that has this capability gives a different value for the capa- 
bility than that in the first termname. 

The order of the other termname entries is significant. Since the terminfo 
compiler tic(lM) does a left-to-right scan of the capabilities, specifying two 
use= entries that contain differing entries for the same capabilities will pro- 
duce different results depending on the order that the entries are given in. 
infocmp will flag any such inconsistencies between the other termname 
entries as they are found. 

Alternatively, specifying a capability after a use= entry that contains that 
capability v^l cause the second specification to be ignored. Using infocmp 
to recreate a description can be a useful check to make sure that everything 
was specified correctly in the original source description. 

Another error that does not cause incorrect compiled files, but will slow 
down the compilation time, is specifying extra use= fields that are superflu- 
ous, infocmp will flag any other termname use= fields that were not 
needed. 

Other Options [-s dli.'llc] [-v] [-V] [-1] [-w width] 

-s sort the fields v^thin each type according to the argument below: 

d leave fields in the order that they are stored in the terminfo 
database. 

i sort by terminfo name. 

1 sort by the long C variable name. 

c sort by the termcap name. 

If no -s option is given, the fields printed out will be sorted alpha- 
betically by the terminfo name within each type, except in the case 
of the -C or the -L options, which cause the sorting to be done by 
the termcap name or the long C variable name, respectively. 

-V print out tracing information on standard error as the program 
runs. 

-V print out the version of the program in use on standard error and 
exit. 

-1 cause the fields to printed out one to a line. Otherwise, the fields 
will be printed several to a line to a maximum width of 60 charac- 
ters. 

-w change the output to width characters. 

Changing Databases [-A directory] [~B directory] 

The location of the compiled terminfo{4:) database is taken from the environ- 
ment variable TERMINFO. If the variable is not defined, or the terminal is 
not found in that location, the system terminfo{4) database, usually in 
/usr /lib /terminfo, will be used. The options -A and -B may be used to 
override this location. The -A option will set TERMINFO for the first term- 
name and the -B option will set TERMINFO for the other termnames. With 
this, it is possible to compare descriptions for a terminal with the same 
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name located in two different databases. This is useful for comparing 
descriptions for the same terminal created by different people. Otherwise 
the terminals would have to be named differently in the terminfo(4) data- 
base for a comparison to be made. 

FILES 

/usr/lib/terminfo/?/* compiled terminal description database 

DIAGNOSTICS 

malloc is out of space! 

There was not enough memory available to process all the 
terminal descriptions requested. Run infocmp several 
times, each time including a subset of the desired term- 
names. 

use= order dependency found: 

A value specified in one relative terminal specification was 
different from that in another relative terminal specifica- 
tion. 

'use=ferm' did not add anything to the description. 

A relative terminal name did not contribute anything to 
the final description. 

must have at least two terminal names for a comparison to be done. 

The -u, -d and -c options require at least two terminal 
names. 

SEE ALSO 

tic(lM), curses(3X), term(4), terminfo(4). 

captoinfo(lM) in the User's/System Administrator's Reference Manual 
Chapter 10 of the Programmer's Guide. 

NOTE 

The termcap database (from earlier releases of UNIX System V) may not be 
supplied in future releases. 



- 4 - 



LD(1) 



(C Software Development Set) 



LD(1) 



NAME 

Id - link editor for common object files 

SYNOPSIS 

Id [options] file name 

DESCRIPTION 

The Id command combines several object files into one, performs relocation, 
resolves external symbols, and supports symbol table information for sym- 
bolic debugging. In the simplest case, the names of several object programs 
are given, and Id combines the objects, producing an object module that can 
either be executed or, if the -r option is specified, used as input for a subse- 
quent Id run. The output of Id is left in a.out. By default this file is execut- 
able if no errors occurred during the load. If any input file, filename, is not 
an object file. Id assumes it is either an archive library or a text file contain- 
ing link editor directives. [See Link Editor Directives in the UNIX System V 
Programmer's Guide for a discussion of input directives.] 

If any argument is a library, it is searched exactly once at the point it is 
encountered in the argument list. The library may be either a relocatable 
archive library or a shared library. [See Shared Libraries in the UNIX System 
V Programmer's Guide for a discussion of shared libraries.] Only those rou- 
tines defining an unresolved external reference are loaded. The library 
(archive) symbol table [see flr(4)] is searched sequentially with as many 
passes as are necessary to resolve external references which can be satisfied 
by library members. Thus, the ordering of library members is functionally 
unimportant, unless there exist multiple library members defining the same 
external symbol. 

The following options are recognized by Id: 
-e epsym 

Set the default entry point address for the output file to be that of 
the symbol epsym . 

"ifill Set the default fill pattern for "holes" within an output section as 
well as initialized bss sections. The argument //// is a two-byte con- 
stant. 

"he Search a library libx.a, where x is up to nine characters. A library is 
searched when its name is encountered, so the placement of a -I is 
significant. By default, libraries are located in LIBDIR or LLIBDIR. 

-m Produce a map or listing of the input/output sections on the stand- 
ard output. 

-o outfile 

Produce an output object file by the name outfile. The name of the 
default object file is a.out. 

-r Retain relocation entries in the output object file. Relocation entries 
must be saved if the output file is to become an input file in a sub- 
sequent Id run. The link editor will not complain about unresolved 
references, and the output file will not be executable. 
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-a Create an absolute file. This is the default if the -r option is not 
used. Used with the -r option, -a allocates memory for common 
symbols. 

-8 Strip line number entries and symbol table information from the 
output object file. 

-t Turn off the warning about multiply-defined symbols that are not 
the same size. 

-u symname 

Enter symname as an undefined symbol in the symbol table. This is 
useful for loading entirely from a library, since initially the symbol 
table is empty and an unresolved reference is needed to force the 
loading of the first routine. The placement of this option on the Id 
line is significant; it must be placed before the library which will 
define the symbol. 

-X Do not preserve local symbols in the output symbol table; enter 
external and static symbols only. This option saves some space in 
the output file. 

-z Do not bind anything to address zero. This option will allow run- 
time detection of null pointers. 

-L dir Change the algorithm of searching for libjc.a to look in dir before 
looking in LIBDIR and LLIBDIR. This option is effective only if it 
precedes the -1 option on the command line. 

-M Output a message for each multiply-defined external definition. 

-N Put the text section at the beginning of the text segment rather than 
after all header information, and put the data section immediately 
following text in the core image. 

-V Output a message giving information about the version of Id being 
used. 

-VS num 

Use num as a decimal version stamp identifpng the a.out file that is 
produced. The version stamp is stored in the optional header. 

-Y[LU\4ir 

Change the default directory used for finding libraries. If L is speci- 
fied, the first default directory which Id searches, LIBDIR, is replaced 
by dir. If U is specified and Id has been built with a second default 
directory, LLIBDIR, then that directory is replaced by dir. If Id was 
built with only one default directory and U is specified a warning is 
printed and the option is ignored. 

FILES 

LIBDIR/Mhx.a 
LLIBDIR/libx.a 
a.out 
LIBDIR 
LLIBDIR 
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SEE ALSO 

as(l), cc(l), mkshlib(l), exit(2), end(3C), a.out(4), ar(4). 

Link Editor Directives and Shared Libraries in the UNIX System V Programmer's 

Guide. 

CAVEATS 

Through its options and input directives, the common link editor gives users 
great flexibility; however, those who use the input directives must assume 
some added responsibilities. Input directives and options should insure the 
following properties for programs: 

C defines a zero pointer as null. A pointer to which zero has been 
assigned must not point to any object. To satisfy this, users must not 
place any object at virtual address zero in the program's address space. 

When the link editor is called through cc(l), a startup routine is linked 
with the user's program. This routine calls exit( ) [see exit(2)] after 
execution of the main program. If the user calls the link editor 
directly, then the user must insure that the program always calls 
exit{ ) rather than falling through the end of the entry routine. 
The symbols etext, edata, and end [see end(3C)] are reserved and are defined 
by the link editor. It is incorrect for a user program to redefine them. 
If the link editor does not recognize an input file as an object file or an 
archive file, it will assume that it contains link editor directives and will 
attempt to parse it. This will occasionally produce an error message com- 
plaining about "syntax errors". 

Arithmetic expressions may only have one forward referenced symbol per 
expression. 
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NAME 

lex - generate programs for simple lexical tasks 
SYNOPSIS 

lex [ -rctvn ][ file ] ... 

DESCRIPTION 

The lex command generates programs to be used in simple lexical analysis 
of text. 

The input files (standard input default) contain strings and expressions to be 
searched for, and C text to be executed when strings are found. 
A file lex.yy.c is generated which, when loaded with the library, copies the 
mput to the output except when a string specified in the file is found; then 
the corresponding program text is executed. The actual string matched is 
left m yytext, an external character array. Matching is done in order of the 
strings in the file. The strings may contain square brackets to indicate char- 
acter classes, as in [abx-z] to indicate a, b, x, y, and z; and the operators *, 
+, and ? mean respectively any non-negative number of, any positive 
number of, and either zero or one occurrence of, the previous character or 
character class. The character . is the class of all ASCII characters except 
new-lme. Parentheses for grouping and vertical bar for alternation are also 
supported. The notation r{d,e} in a rule indicates between d and e 
instances of regular expression r. It has higher precedence than I, but lower 
than *, +, and concatenation. Thus [a-zA-Z]+ matches a string of 
letters. The character at the beginning of an expression permits a success- 
ful match only immediately after a new-line, and the character $ at the end 
of an expression requires a trailing new-line. The character / in an expres- 
sion indicates trailing context; only the part of the expression up to the slash 
IS returned in yytext, but the remainder of the expression must follow in the 
input stream. An operator character may be used as an ordinary symbol if 
it is within " symbols or preceded by \. 

Three subroutines defined as macros are expected: inputO to read a charac- 
ter; unput(c) to replace a character read; and output(c) to place an output 
character. They are defined in terms of the standard streams, but you can 
ovemde them. The program generated is named yylexO, and the library 
contains a mainO which calls it. The action REJECT on the right side of the 
rule causes this match to be rejected and the next suitable match executed; 
the function yymoreO accumulates additional characters into the same 
yytext) and the function yyless(p) pushes back the portion of the string 
matched beginning at p, which should be between yytext and 
yytext +yyleng. The macros input and output use files yyin and yyout to 
read from and write to, defaulted to stdin and stdout, respectively. 
Any line beginning with a blank is assumed to contain only C text and is 
copied; if it precedes %%, it is copied into the external definition area of the 
lex.yy.c file. All rules should follow a %%, as in YACC. Lines preceding 
%% which begin with a non-blank character define the string on the left to 
be the remainder of the line; it can be called out later by surrounding it with 
{}. Note that curly brackets do not imply parentheses; only string substitu- 
tion is done. 
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EXAMPLE 

D [0-9] 
%% 

if printf( " IF statement\n " ); 

[a-z]+ printf( " tag, value %s\n " ,yytext); 
{D} + printf( " octal number %s\n " ,yytext); 
{D} + printf( " decimal number %s\n " ,yytext); 
" ++ " printf( " unary op\n " ); 
" 4- " printf ( " binary op\n " ); 
" /*" skipcommntsQ; 
%% 

skipcommntsO 

{ 

for (;;) 

while (inputO != '*') 

if (inputO != '/') 

unput(yytext[yyleng-l]); 

else 

return; 

} 

} 

The external names generated by lex all begin with the prefix yy or YY. 
The flags must appear before any files. The flag -r indicates RATFOR 
actions, -c indicates C actions and is the default, -t causes the lex.yy.c pro- 
gram to be written instead to standard output, -v provides a one-line sum- 
mary of statistics, -n will not print out the -v summary. Multiple files are 
treated as a single file. If no files are specified, standard input is used. 
Certain table sizes for the resulting finite state machine can be set in the 
definitions section: 

o/op n number of positions is n (default 2500) 

o/on n number of states is n (500) 

o/oe n number of parse tree nodes is n (1000) 

%a n number of transitions is n (2000) 

%k n number of packed character classes is n (1000) 

o/oo n size of output array is n (3000) 

The use of one or more of the above automatically implies the -v option, 
unless the -n option is used. 

SEE ALSO 

yacc(l). 

Chapter 5 in the UNIX System V Programmer's Guide. 

BUGS 

The -r option is not yet fully operational. 
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NAME 

lint - a C program checker 
SYNOPSIS 

lint [ option ] ... file ... 

DESCRIPTION 

The lint command attempts to detect features of the C program files that are 
likely to be bugs, non-portable, or wasteful. It also checks type usage more 
stnctly than the compilers. Among the things that are currently detected 
are unreachable statements, loops not entered at the top, automatic vari- 
ables declared and not used, and logical expressions whose value is con- 
stant. Moreover, the usage of functions is checked to find functions that 
return values m some places and not in others, functions called with vary- 
mg numbers or types of arguments, and functions whose values are not 
used or whose values are used but none returned. 

Arguments whose names end with .c are taken to be C source files Argu- 
ments whose names end with .In are taken to be the result of an earlier 
mvocation of lint with either the -c or the -o option used. The .In fUes are 
analogous to o (object) files that are produced by the cc(l) command when 
given a .c file as input. Files with other suffixes are warned about and 
Ignored. 

The lint command will take all the .c, .In, and llib.k.ln (specified by -Lc) 
files and process them in their command line order. By default lint 
appends the standard C lint library (Uib-lcln) to the end of the list of files 
However if the -p option is used, the portable C lint library (Ilib-porUn) is 
appended instead When the -c option is not used, the second pass of lint 
checks this list of files for mutual compatibility. When the -c option is 
used, the .In and the llib-Lc.In files are ignored. 

Any number of lint options may be used, in any order, intermixed with 
file-name arguments. The following options are used to suppress certain 
kinds of complaints: 

-a Suppress complaints about assignments of long values to variables 
that are not long. 

-b Suppress complaints about break statements that cannot be reached 
(Programs produced by lex or yacc will often result in many such 
complaints.) ^ 

Do not apply heuristic tests that attempt to intuit bugs, improve 
style, and reduce waste. 

Suppress complaints about functions and external variables used 
and not defined, or defined and not used. (This option is suitable 
for running lint on a subset of files of a larger program.) 
Suppress complaints about unused arguments in functions. 

Do not report variables referred to by external declarations but 
never used. 
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The following arguments alter lint's behavior: 

-he Include additional lint library llib-bc.ln. For example, you can 
include a lint version of the math library llib-lm.ln by inserting -Im 
on the command line. This argument does not suppress the default 
use of Uib-lcln. These lint libraries must be in the assumed direc- 
tory. This option can be used to reference local lint libraries and is 
useful in the development of multifile projects. 

-n Do not check compatibility against either the standard or the port- 
able lint library. 

-p Attempt to check portability to other dialects (IBM and GCOS) of C. 
Along with stricter checking, this option causes all non-external 
names to be truncated to eight 'characters and all external names to 
be truncated to six characters and one case. 

-c Cause lint to produce a .In file for every .c file on the command 
line. These .In files are the product of lint's first pass only, and are 
not checked for inter-function compatibility. 

-o lib Cause lint to create a lint library with the name llib-Uz&.ln. The -c 
option nullifies any use of the -o option. The lint library produced 
is the input that is given to lint's second pass. The -o option sim- 
ply causes this file to be saved in the named lint library. To pro- 
duce a llib-1/fb.ln without extraneous messages, use of the -x 
option is suggested. The -v option is useful if the source file(s) for 
the lint library are just external interfaces (for example, the way the 
file Uib-lc is written). These option settings are also available 
through the use of "lint comments" (see below). 

The -D, -U, and -I options of cpp(l) and the -g and -O options of cc(l) are 
also recognized as separate arguments. The -g and -O options are ignored, 
but, by recognizing these options, lint's behavior is closer to that of the 
cc(l) command. Other options are warned about and ignored. The prepro- 
cessor symbol "lint" is defined to allow certain questionable code to be 
altered or removed for lint. Therefore, the symbol "lint" should be thought 
of as a reserved word for all code that is planned to be checked by lint. 

Certain conventional comments in the C source will change the behavior of 
lint: 

/♦NOTREACHED*/ 

at appropriate points stops comments about unreachable 
code. [This comment is typically placed just after calls to 
functions like exit (2).] 

/♦VARARGSn*/ 

suppresses the usual checking for variable numbers of argu- 
ments in the following function declaration. The data types 
of the first n arguments are checked; a missing n is taken to 
be 0. 

/♦ARGSUSED*/ 

turns on the -v option for the next function. 
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FILES 



/*LINTLIBRARY*/ 

at the beginning of a file shuts off complaints about unused 
functions and function arguments in this file. This is 
equivalent to using the -v and -x options. 

The lint command produces its first output on a per-source-file basis. Com- 
plaints regarding included fUes are collected and printed after all source files 
have been processed. Finally, if the -c option is not used, information gath- 
ered from all input files is collected and checked for consistency. At this 
pomt, if it is not clear whether a complaint stems from a given source file or 
from one of its included fUes, the source file name will be printed followed 
by a question mark. 

The behavior of the -c and the -o options allows for incremental use of lint 
on a set of C source files. Generally, one invokes lint once for each source 
file with the -c option. Each of these invocations produces a .In file for 
each .€ file, and prints all messages that are about just that source file 
After all the source files have been separately run through lint, it is invoked 
once more (without the -c option), listing all the .In files with the needed 
-Ix options. This will print all the interfile inconsistencies. This scheme 
works well with ma^e(l); it allows make to be used to lint only the source 
files that have been modified since the last time the set of source files were 
Itnted. 



LLIBDIR the directory where the lint libraries specified by the 

-Ix option must exist, usually /usr/lib 
LLIBDIR/\mt[12] first and second passes 

LL/BD/R/Uib-lc.ln declarations for C Library functions (binary format- 
source is in LUBDIR/llib-lc) 

LL/BD/R/llib-port.ln declarations for portable functions (binary formal- 
source is in LL/BD/R/Uib-port) 

LL7BD/R/llib-lm.ln declarations for Math Library functions (binary for- 
mat; source is in LLIBDIR/l\ih-lm) 

TMPDIR/*lm\* temporaries 

TMPDIR usually /usr/tmp but can be redefined by setting the 

environment variable TMPDIR [see tempnami) in 
tmvnam(3S)]. 

SEE ALSO 

cc(l), cpp(l), make(l). 

BUGS 

exit{2), setjmp{3C), and other functions that do not return are not under- 
stood; this causes various lies. 
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NAME 

list - produce C source listing from a commor\ object file 
SYNOPSIS 

list [-V] [-h] [-F function] source-file . . . [object-file] 
DESCRIPTION 

The list command produces a C source listing with line number information 
attached. If multiple C source files were used to create the object file, list 
will accept multiple file names. The object file is taken to be the last non-C 
source file argument. If no object file is specified, the default object file, 
a.out, will be used. 

Line numbers will be printed for each line marked as breakpoint inserted by 
the compiler (generally, each executable C statement that begins a new line 
of source). Line numbering begins anew for each function. Line number 1 
is always the line containing the left curly brace ( { ) that begins the function 
body. Line numbers will also be supplied for inner block redeclarations of 
local variables so that they can be distinguished by the symbolic debugger. 

The following options are interpreted by list and may be given in any order: 
-V Print, on standard error, the version number of the list com- 

mand executing. 

-h Suppress heading output. 

-IPfunction List only the named function. The -F option may be specified 
multiple times on the command line. 

SEE ALSO 

as(l), cc(l), ld(l). 

DIAGNOSTICS 

The list command will produce the error message "list: name: cannot open 
if name cannot be read. If the source file names do not end in .c , the mes- 
sage is "list: name: invalid C source name". An invalid object file will 
cause the message "list: name: bad magic" to be produced. If some or all of 
the symbolic debugging information is missing, one of the following mes- 
sages will be printed: "list: name: symbols have been stripped, cannot 
proceed", "list: name: cannot read line numbers", and "list: name: not in 
symbol table". The foUovydng messages are produced when list has become 
confused by #ifdef s in the source file: "list: name: cannot find function in 
symbol table", "list: name: out of sync: too many }", and "list: name: unex- 
pected end-of-file". The error message "list: name: missing or inappropriate 
line numbers" means that either symbol debugging information is missing, 
or list has been confused by C preprocessor statements. 

CAVEATS 

Object files given to list must have been compiled with the -g option of 
cc(l). 

Since list does not use the C preprocessor, it may be unable to recognize 
function definitions whose syntax has been distorted by the use of C 
preprocessor macro substitutions. 
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NAME 

lorder - find ordering relation for an object library 
SYNOPSIS 

lorder file ... 

DESCRIPTION 

The input is one or more object or library archive files [see flr(l)]. The 
standard output is a list of pairs of object file or archive member names, 
meaning that the first file of the pair refers to external identifiers defined in 
the second. The output may be processed by tsort{l) to find an ordering of 
a library suitable for one-pass access by ld(l). Note that the link editor 
ld{l) is capable of multiple passes over an archive in the portable archive 
format [see flr(4)] and does not require that lorder{l) be used when building 
an archive. The usage of the lorder(l) command may, however, allow for a 
slightly more efficient access of the archive during the link edit process. 
The following example builds a new library from existing .o files, 
ar -cr library border *.o | tsort' 

FILES 

TMPD7R/*symref temporary files 
TMPD/R/*symdef temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environ- 
ment variable TMPDIR [see tempnamQ in tmpnam(3S)]. 

SEE ALSO 

ar(l), ld(l), tsort(l), ar(4). 

CAVEAT 

The lorder command will accept as input any object or archive file, regard- 
less of its suffix, provided there is more than one input file. If there is but a 
single input file, its suffix must be .o. 
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NAME 

Iprof - display line-by-line execution count profile data 
SYNOPSIS 

Iprof [-p] [-8] [-X] [[-I incdir]] [[-r srcfile]] [-c cntfile] [-o prog] 
Iprof -m filel.cnt file2.cnt [ [ filen.cnt ] ] [-T] -d destfile.cnt 

DESCRIPTION 

Iprof is a tool for dynamic analysis; that is, the analysis of a program at run 
time. Specifically, Iprof identifies the most frequently executed parts of 
source code and parts of code that are never executed. 

Iprof interprets a profile file (prog.cnt by default) produced by the profiled 
program prog {a,out by default) that has been compiled with the -ql option 
of cc(l). This cc command option arranges for code to be inserted to record 
run-time behavior and for data to be written to a file at the end of execu- 
tion. 

By default, Iprof prints a listing of source files (the names of vy^hich are 
stored in the symbol table of the executable file), each line preceded by its 
line number (in the file) and the number of times it v^as executed. 

The following options may appear singly or be combined in any order: 

-p Print listing, each line preceded by the line number and the number 
of times it was executed (default). This option can be used together 
with the -s option to print both the source listing and summary 
information. 

-s Print summary information of percentage of lines of code executed 
per function. 

-X Instead of printing the execution count numbers for each line, print 
each line preceded by its line number and a [U] if the line was not 
executed. If the line was executed, print only the line number. 

-I incdir 

Look for source or header files in the directory incdir in addition to 
the current directory and the standard place for #include files (usu- 
ally /usr/include). You can specify more than one directory with 
-I on one command line. 

-r srcfile 

Instead of printing all source files, print only those files named in -r 
options (to be used with the -p option only). You can specify mul- 
tiple files v^th -r on one command line. 

-c cntfile 

Use the file cntfile instead of prog.cnt as the input profile file. 

-o prog Use the name of the program prog instead of the name used when 
creating the profile file. Because the program name stored in the 
profile file contains the relative path, this option is necessary if the 
executable file or profile file has been moved. 
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Merging Data Files 

Iprof can also be used to merge data files. The -m option must be accom- 
panied with the -d option: 

-m filelxnt filel.cnt \filen.cnt] -d destfile.cnt 

Merge the data files filel.cnt through filen.cnt by summing the exe- 
cution counts per line, so that data from several runs can be accu- 
mulated. The result is written to destfile.cnt. The data files must 
contain profiling data for the same prog (see the -T option below). 

-T Time stamp override. Normally, the time stamps of the executable 
files being profiled are checked, and data files vsdll not be merged if 
the time stamps do not match. If -T is specified, this check is 
skipped. 

Controlling the Run Time Profiling Environment 

The environment variable PROFOFTS provides run time control over profil- 
ing. When a profiled program is about to terminate, it examines the value 
of PROFOPTS to determine how the profiling data is to be handled. 

The environment variable PROFOPTS is a comma-separated list of options 
interpreted by the program being profiled. If PROFOPTS is not defined in 
the environment, then the default action is taken: the profiling data is 
saved in a file (with the default name, prog.cnt) in the current directory. If 
PROFOPTS is set to the null string, no profiling data is saved. The follow- 
ing are the available options: 

msg=[yl n] 

If msg=y is specified, a message stating that profile data is being 
saved is printed to stderr. If msg=n is specified, print only profiling 
error messages. The default is msg=y. 

merge=[yl n] 

If merge=n is specified, do not merge data files after successive 
runs. The data file is overwritten after each execution. If merge=y 
is specified, the data will be merged. The merge will fail if the pro- 
gram has been recompiled; the data file will be left in TMPDIR. The 
default is ]nerge=n. 

pid=[y!n] 

If pid=y is specified, the name of the data file will include the pro- 
cess ID of the profiled program. This allows the creation of dif- 
ferent data files for programs calling fork{2). If pid=n is specified, 
the default name is used. The default is pid=n. 

dir=dimame 

Place the data file in the directory dirname if this option is speci- 
fied. Otherwise, the data file is created in the directory that is 
current at the end of execution. 

Hle^filename 

Use filename as the name of the data file in dir created by the pro- 
filed program if this option is specified. Otherwise, the default 
name is used. 
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FILES 

prog.cnt for profile data 
TMPDIR/* temporary files 

TMPDIR is usually /usr/tmp, but can be redefined by setting the environ- 
ment variable TMPDIR [see tempnam{ ) in tmpnam{3S)]. 

SEE ALSO 

cc(l), prof(l), fork(2), tmpnam(3S). 

WARNINGS 

For the -m option, if destfile.cnt exists, its previous contents are destroyed. 

Optimizing functions may result in the loss of some line number informa- 
tion and may result in code motions, both of v^hich may make Iprof infor- 
mation unreliable. 

Different parts of one line of a source file may be executed different 
numbers of times (e.g., the for loop belov^); the count corresponds to the 
first part of the line. For example, in the following for loop 

1 [8] for (j = 0; j < 5; j++) 
5 [9] sub(j); 

line 8 consists of three parts. The line count listed, however, is for the ini- 
tialization part, i.e., j = 0. 

Iprof incorrectly handles the statement immediately following a for loop 
containing a single if statement. In the following example, line 8 is exe- 
cuted only once. 

1 [5] for (i = 0; i < 3; i++) 

3 [6] if (i > 3) 

[7] X = i; 
3 [8] i = 0; 

This problem can be solved by adding curly braces, as follows: 

1 [5] for (i = 0; i < 3; i++) { 
3 [6] if (i > 3) 

[7] X = i; 
3 [8] } 

1 [9] i = 0; 

Iprof then handles the statement following the for loop correctly. 

Iprof does not provide execution information about case statements contain- 
ing only a break statement, or about return statements without a value. 

1 [4] switch (i) { 
case : 

break ; 
default : 

[8] i = 0; 

} 

1 [11] if (i 1= 0) 

return ; 
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NAME 

m4 - macroprocessor 

SYNOPSIS 

m4 [ options ] [ files ] 

DESCRIPTION 

The m4 command is a macroprocessor intended as a front end for Ratfor, C, 
and other languages. Each of the argument files is processed in order; if 
there are no files, or if a file name is the standard input is read. The pro- 
cessed text is written on the standard output. 

The options and their effects are as follows: 

-e Operate interactively. Interrupts are ignored and the output is 
unbuffered. 

-s Enable line sync output for the C preprocessor (#line . . . ) 

'Bint Change the size of the push-back and argument collection buffers 
from the default of 4,096. 

-Hint Change the size of the symbol table hash array from the default of 
199. The size should be prime. 

-Sint Change the size of the call stack from the default of 100 slots. 
Macros take three slots, and non-macro arguments take one. 

-Tint Change the size of the token buffer from the default of 512 bytes. 

To be effective, these flags must appear before any file names and before 
any -D or -U flags: 

■-Dname[=val] 

Defines name to val or to null in vaVs absence. 

'Vname 

Undefines name. 
Macro calls have the form: 

name(argl,arg2, . . ., argn) 

The ( must immediately follow the name of the macro. If the name of a 
defined macro is not followed by a (, it is deemed to be a call of that macro 
with no arguments. Potential macro names consist of alphabetic letters, 
digits, and underscore _, where the first character is not a digit. 

Leading unquoted blanks, tabs, and new-lines are ignored while collecting 
arguments. Left and right single quotes are used to quote strings. The 
value of a quoted string is the string stripped of the quotes. 

When a macro name is recognized, its arguments are collected by searching 
for a matching right parenthesis. If fewer arguments are supplied than are 
in the macro definition, the trailing arguments are taken to be null. Macro 
evaluation proceeds normally during the collection of the arguments, and 
any commas or right parentheses which happen to turn up within the value 
of a nested call are as effective as those in the original input text. After 
argument collection, the value of the macro is pushed back onto the input 
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stream and rescanned. 

The m4 command makes available the following built-in macros. They may 
be redefined, but once this is done, the original meaning is lost. Their 
values are null unless otherwise stated. 

define the second argument is installed as the value of the macro 

whose name is the first argument. Each occurrence of $n in 
the replacement text, where n is a digit, is replaced by the n- 
th argument. Argument is the name of the macro; missing 
arguments are replaced by the null string; $# is replaced by 
the number of arguments; $* is replaced by a list of all the 
arguments separated by commas; $@ is like $*, but each 
argument is quoted (with the current quotes). 

removes the definition of the macro named in its argument. 

returns the quoted definition of its argument(s). It is useful 
for renaming macros, especially built-ins. 

like define, but saves any previous definition. 



undefine 
defn 

pushdef 
popdef 

ifdef 



removes current definition of its argument(s), exposing the 
previous one, if any. 

if the first argument is defined, the value is the second argu- 
ment, otherwise the third. If there is no third argument, the 
value is null. The word unix is predefined on UNIX system 
versions of m4. 

shift returns all but its first argument. The other arguments are 

quoted and pushed back with commas in between. The quot- 
ing nullifies the effect of the extra scan that will subsequently 
be performed. 

changequote change quote symbols to the first and second arguments. The 
symbols may be up to five characters long. Changequote 
without arguments restores the original values (i.e., * '). 

changecom change left and right comment markers from the default # 
and new-line. With no arguments, the comment mechanism 
is effectively disabled. With one argument, the left marker 
becomes the argument and the right marker becomes new- 
line. With two arguments, both markers are affected. Com- 
ment markers may be up to five characters long. 

divert m4 maintains 10 output streams, numbered 0-9. The final 

output is the concatenation of the streams in numerical order; 
initially stream is the current stream. The divert macro 
changes the current output stream to its (digit-string) argu- 
ment. Output diverted to a stream other than through 9 is 
discarded. 

undivert causes immediate output of text from diversions named as 
arguments, or all diversions if no argument. Text may be 
undiverted into another diversion. Undiverting discards the 
diverted text. 
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divnum returns the value of the current output stream. 

dnl reads and discards characters up to and including the next 

new-line. 

ifelse has three or more arguments. If the first argument is the 

same string as the second, then the value is the third argu- 
ment. If not, and if there are more than four arguments, the 
process is repeated with arguments 4, 5, 6, and 7. Otherwise, 
the value is either the fourth string, or, if it is not present, 
null. 

incr returns the value of its argument incremented by 1. The 

value of the argument is calculated by interpreting an initial 
digit-string as a decimal number. 

deer returns the value of its argument decremented by 1. 

eval evaluates its argument as an arithmetic expression, using 32- 

bit arithmetic. Operators include +, -, *, /, %, " (exponentia- 
tion), bitwise &, |, and relational; parentheses. Octal 
and hex numbers may be specified as in C. The second argu- 
ment specifies the radix for the result; the default is 10. The 
third argument may be used to specify the minimum number 
of digits in the result. 

len returns the number of characters in its argument. 

index returns the position in its first argument where the second 

argument begins (zero origin), or -1 if the second argument 
does not occur. 

substr returns a substring of its first argument. The second argu- 

ment is a zero origin number selecting the first character; the 
third argument indicates the length of the substring. A miss- 
ing third argument is taken to be large enough to extend to 
the end of the first string. 

translit. transliterates the characters in its first argument from the set 
given by the second argument to the set given by the third. 
No abbreviations are permitted. 

include returns the contents of the file named in the argument. 

sinclude is identical to include, except that it says nothing if the file is 
inaccessible. 

syscmd executes the UNIX system command given in the first argu- 

ment. No value is returned. 

sysVal is the return code from the last call to syscmd. 

maketemp fills in a string of XXXXX in its argument with the current pro- 
cess ID. 

m4exit causes immediate exit from m4. Argument 1, if given, is the 

exit code; the default is 0. 
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m4wrap 

errprint 
dumpdef 

traceon 

traceoff 



SEE ALSO 

cc(l), cpp(l). 



argument 1 will be pushed back at final EOF; example: 
m4wrap(*cleanup( )') 

prints its argument on the diagnostic output file. 

prints current names and definitions for the named items or 
for all if no arguments are given. 

v^ith no arguments, turns on tracing for all macros (including 
built-ins). Otherv^ise, turns on tracing for named macros. 

turns off trace globally and for any macros specified. Macros 
specifically traced by traceon can be untraced only by specific 
calls to traceoff. 
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NAME 

make - maintain, update, and regenerate groups of programs 
SYNOPSIS 

make [-f makefile] [-p] [-i] [-k] [-s] [-r] [-n] [-b] [-e] [-u] [-t] [-q] 
[ names ] 

DESCRIPTION 

make allows the programmer to maintain, update, and regenerate groups of 
computer programs. The following is a brief description of all options and 
some special names: 

-f makefile Description file name, makefile is assumed to be the name of a 
description file. 

-p Print out the complete set of macro definitions and target 

descriptions. 

-i Ignore error codes returned by invoked commands. This mode 

is entered if the fake target name .IGNORE appears in the 
description file. 

-k Abandon work on the current entry if it fails, but continue on 

other branches that do not depend on that entry. 

-s Silent mode. Do not print command lines before executing. 

This mode is also entered if the fake target name .SILENT 
appears in the description file. 

-r Do not use the built-in rules. 

-n No execute mode. Print commands, but do not execute them. 

Even lines beginning with an @ are printed. 

-b Compatibility mode for old makefiles. 

-e Environment variables override assignments within makefiles. 

-t Touch the target files (causing them to be up-to-date) rather 

than issue the usual commands. 

-q Question. The make command returns a zero or non-zero 

status code depending on whether the target file is or is not 
up-to-date. 

.DEFAULT If a file must be made but there are no explicit commands or 
relevant built-in rules, the commands associated with the name 
.DEFAULT are used if it exists. 

.PRECIOUS Dependents of this target wall not be removed when quit or 
interrupt are hit. 

.SILENT Same effect as the -s option. 

.IGNORE Same effect as the -i option. 

make executes conunands in makefile to update one or more target names. 
Name is typically a program. If no -f option is present, makefile. Makefile, 
and the Source Code Control System (SCCS) files s.makefile, and 
s.Makefile are tried in order. If makefile is the standard input is taken. 
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More than one -f makefile argument pair may appear. 

make updates a target only if its dependents are newer than the target. All 
prerequisite files of a target are added recursively to the list of targets. 
Missing files are deemed to be out-of-date. 

makefile contains a sequence of entries that specify dependencies. The first 
line of an entry is a blank-separated, non-null list of targets, then a :, then a 
(possibly null) list of prerequisite files or dependencies. Text following a ; 
and all following lines that begin with a tab are shell commands to be exe- 
cuted to update the target. The first non-empty line that does not begin 
with a tab or # begins a new dependency or macro definition. Shell com- 
mands may be continued across lines with the <backslash><new-line> 
sequence. Everything printed by makefl (except the initial tab) is passed 
directly to the shell as is. Thus, 

echo a\ 
b 

will produce 
ab 

exactly the same as the shell would. 

Sharp (#) and new-line surround comments. 

The following makefile says that pgm depends on two files a.o and b.o, and 
that they in turn depend on their corresponding source files (a.c and b.c) 
and a common file incLh: 

pgm: a.o b.o 

cc a.o b.o -o pgm 

a. o: incl.h a.c 

cc -c a.c 

b. o: incl.h b.c 

cc -c b.c 

Command lines are executed one at a time, each by its own shell. The 
SHELL environment variable can be used to specify which shell make should 
use to execute commands. The default is /bin/sh. The first one or two 
characters in a command can be the following: -, @, -@, or @-. If @ is 
present, printing of the command is suppressed. If - is present, make 
ignores an error. A line is printed when it is executed unless the -s option 
is present, or the entry .SILENT: is in makefile, or unless the initial character 
sequence contains a @. The -n option specifies printing without execution; 
however, if the command line has the string $(MAKE) in it, the line is 
always executed (see discussion of the MAKEFLAGS macro under Environ- 
ment), The -t (touch) option updates the modified date of a file without 
executing any commands. 

Commands returning non-zero status normally terminate make. If the -i 
option is present, or the entry .IGNORE: appears in makefile, or the initial 
character sequence of the command contains -, the error is ignored. If the 
-k option is present, work is abandoned on the current entry, but continues 
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on other branches that do not depend on that entry. 

The -b option allows old makefiles (those written for the old version of 
make) to run without errors. 

Interrupt and quit cause the target to be deleted unless the target is a depen- 
dent of the special name .PRECIOUS. 

Environment 

The environment is read by make. All variables are assumed to be macro 
definitions and processed as such. The environment variables are processed 
before any makefile and after the internal rules; thus, macro assignments in 
a makefile override environment variables. The -e option causes the 
environment to override the macro assignments in a makefile. Suffixes and 
their associated rules in the makefile will override any identical suffixes in 
the built-in rules. 

The MAKEFLAGS environment variable is processed by make as containing 
any legal input option (except -f and -p) defined for the command line. 
Further, upon invocation, make "invents" the variable if it is not in the 
environment, puts the current options into it, and passes it on to invocations 
of commands. Thus, MAKEFLAGS always contains the current input 
options. This proves very useful for "super-makes". In fact, as noted 
above, when the -n option is used, the command $(MAKE) is executed any- 
way; hence, one can perform a make -n recursively on a whole software 
system to see what would have been executed. This is because the -n is 
put in MAKEFLAGS and passed to further invocations of $(MAKE). This is 
one way of debugging all of the makefiles for a software project without 
actually doing anything. 

Include Files 

If the string include appears as the first seven letters of a line in a makefile, 
and is followed by a blank or a tab, the rest of the line is assumed to be a 
filename and will be read by the current invocation, after substituting for 
any macros. 

Macros 

Entries of the form stringl = string! are macro definitions. String! is 
defined as all characters up to a comment character or an unescaped new- 
line. Subsequent appearances of ${stringl[:substl=[subst2]]) are replaced by 
stringl. The parentheses are optional if a single character macro name is 
used and there is no substitute sequence. The optional :substl=subst2 is a 
substitute sequence. If it is specified, all non-overlapping occurrences of 
substl in the named macro are replaced by substl. Strings (for the purposes 
of this type of substitution) are delimited by blanks, tabs, new-line charac- 
ters, and beginnings of lines. An example of the use of the substitute 
sequence is shown under Libraries. 

Internal Macros 

There are five internally maintained macros that are useful for writing rules 
for building targets. 

$* The macro $* stands for the filename part of the current dependent 
with the suffix deleted. It is evaluated only for inference rules. 



-3- 



MAKE(l) 



(C Software Development Set) 



MAKE(l) 



$@ The $@ macro stands for the full target name of the current target. It 
is evaluated only for explicitly named dependencies. 

$< The $< macro is only evaluated for inference rules or the .DEFAULT 
rule. It is the module that is out-of-date with respect to the target (i.e., 
the "manufactured" dependent file name). Thus, in the .c.o rule, the 
$< macro would evaluate to the .c file. An example for making 
optimized .o files from .c files is: 

.c.o: 

cc -c -O $*.c 

or: 

.c.o: 

cc -c -O $< 

$? The $? macro is evaluated when explicit rules from the makefile are 
evaluated. It is the list of prerequisites that are out-of-date with 
respect to the target; essentially, those modules which must be rebuilt. 

$% The $% macro is only evaluated when the target is an archive library 
member of the form lib(file.o). In this case, $@ evaluates to lib and 
$% evaluates to the library member, file.o. 

Four of the five macros can have alternative forms. When an uppercase D 
or F is appended to any of the four macros, the meaning is changed to 
"directory part" for D and "file part" for F. Thus, $(@D) refers to the 
directory part of the string $@. If there is no directory part, ./ is generated. 
The only macro excluded from this alternative form is $?. 

Suffixes 

Certain names (for instance, those ending with .o) have inferable prere- 
quisites such as .€, .s, etc. If no update commands for such a file appear in 
makefile, and if an inferable prerequisite exists, that prerequisite is compiled 
to make the target. In this case, make has inference rules which allow 
building files from other files by examining the suffixes and determining an 
appropriate inference rule to use. The current default inference rules are: 

.c .c" .f .r .sh .sh" 
.CO .c.a .c~.o .c^.c .c^.a 

.f.o .f.a .r.o .r.f .r.a 

.h".h .s.o .s^.o .s'.s .s".a .sh^.sh 

.1.0 .i.c .r.o .r.i .r.c 

.y.o .y.c .y^.o .y".y .y'.c 

The internal rules for make are contained in the source file rules.c for the 
make program. These rules can be locally modified. To print out the rules 
compiled into the make on any machine in a form suitable for recompila- 
tion, the following command is used: 

make -fp - 2>/dev/null </dev/null 
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A tilde in the above rules refers to an SCCS file [see sccsfile{4)]. Thus, the 
rule .€".0 would transform an SCCS C source file into an object file (.o). 
Because the s. of the SCCS files is a prefix, it is incompatible with make's 
suffbc point of view. Hence, the tilde is a way of changing any file refer- 
ence into an SCCS file reference. 

A rule with only one suffix (i.e., .c:) is the definition of how to build x from 
XX, In effect, the other suffix is null. This is useful for building targets 
from only one source file (e.g., shell procedures, simple C programs). 

Additional suffixes are given as the dependency list for .SUFFIXES. Order is 
significant; the first possible name for which both a file and a rule exist is 
inferred as a prerequisite. The default list is: 

.SUFFIXES: .o .c .c" .y .y" .1 .r .s .s" .sh .sh* .h .h~ .f .r 

Here again, the above command for printing the internal rules will display 
the list of suffixes implemented on the current machine. Multiple suffix lists 
accumulate; .SUFFIXES: with no dependencies clears the list of suffbces. 

Inference Rules 

The first example can be done more briefly. 

pgm: a.o b.o 

cc a.o b.o -o pgm 
a.o b.o: incl.h 

This is because make has a set of internal rules for building files. The user 
may add rules to this list by simply putting them in the makefile. 

Certain macros are used by the default inference rules to permit the inclu- 
sion of optional matter in any resulting commands. For example, CFLAGS, 
LFLAGS, and YFLAGS are used for compiler options to cc(l), lex{l\ and 
yacc{l), respectively. Again, the previous method for examining the current 
rules is recommended. 

The inference of prerequisites can be controlled. The rule to create a file 
with suffix .o from a file with suffix .c is specified as an entry with .c.o: as 
the target and no dependents. Shell commands associated with the target 
define the rule for making a .o file from a .c file. Any target that has no 
slashes in it and starts vsdth a dot is identified as a rule and not a true target. 

Libraries 

If a target or dependency name contains parentheses, it is assumed to be an 
archive library, the string within parentheses referring to a member within 
the library. Thus lib(£ile.o) and $(LIB)(file.o) both refer to an archive library 
that contains file.o. (This assumes the LIB macro has been previously 
defined.) The expression $(LIB)(£ilel.o file2.o) is not legal. Rules pertaining 
to archive libraries have the form .XX. a where the XX is the suffix from 
which the archive member is to be made. 

An unfortunate byproduct of the current implementation requires the XX to 
be different from the suffix of the archive member. Thus, one cannot have 
lib(file.o) depend upon file.o explicitly. The most common use of the 
archive interface follows. Here, we assume the source files are all C type 
source: 
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lib: lib(filel.o) Ub(fae2.o) lib(file3.o) 
@echo lib is now up-to-date 

.c.a: 

$(CC) -c $(CFLAGS) $< 
$(AR) $(ARFLAGS) $@ $*.o 
rm -f $*.o 

In fact, the .c.a rule listed above is built into make and is unnecessary in this 
example. A more interesting, but more limited example of an archive 
library maintenance construction follows: 

lib: lib(filel.o) lib(file2.o) lib(fUe3.o) 
$(CC) -c $(CFLAGS) $(?:.o=.c) 
$(AR) $(ARFLAGS) lib $? 
rm $? @echo lib is now up-to-date 

.c.a:; 

Here the substitution mode of the macro expansions is used. The $? list is 
defined to be the set of object filenames (inside lib) whose C source files 
are out-of-date. The substitution mode translates the .o to .c. (Unfor- 
tunately, one cannot as yet transform to .c"; however, this may become pos- 
sible in the future.) Note also, the disabling of the .c.a: rule, which would 
have created each object file, one by one. This particular construct speeds 
up archive library maintenance considerably. This type of construct 
becomes very cumbersome if the archive library contains a mix of assembly 
programs and C programs. 

HLES 

[Mm]akefile and s.[Mm]akefile 
/bin/sh 

SEE ALSO 

cc(l), lex(l), yacc(l), printf(3S), sccsfile(4). 

cd(l), sh(l) in the User's /System Administrator's Reference Manual. 

NOTES 

Some commands return non-zero status inappropriately; use -i to overcome 
the difficulty. 

BUGS 

Filenames with the characters =, :, or @ will not work. Commands that are 
directly executed by the shell, notably cd(l), are ineffectual across new-lines 
in make. The syntax (lib(filel.o file2.o fileS.o)) is illegal. You cannot build 
lib(file.o) from file.o. The macro $(a:.o=.c") does not work. Named pipes 
are not handled well. 
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NAME 

mcs - manipulate the object file comment section 
SYNOPSIS 

mcs [options] object-file ... 

DESCRIPTION 

The mcs command manipulates the comment section, normally the ".com- 
ment" section, in an object file. It is used to add to, delete, print, and 
compress the contents of the comment section in a UNIX system object file. 
The mcs command must be given one or more of the options described 
below. It takes each of the options given and applies them in order to the 
object-files. 

If the object file is an archive, the file is treated as a set of individual object 
files. For example, if the -a option is specified, the string is appended to 
the comment section of each archive element. 

The foUovdng options are available. 

-a string 

Append string to the comment section of the object-files. If string 
contains embedded blanks, it must be enclosed in quotation marks. 

-c Compress the contents of the comment section. All duplicate 
entries are removed. The ordering of the remaining entries is not 
disturbed. 

-d Delete the contents of the comment section from the object file. 

The object file comment section header is removed also, 
-n name 

Specify the name of the section to access. By default, mcs deals 
v^th the section named .comment. This option can be used to 
specify another section. 

-p Print the contents of the comment section on the standard output. 
If more than one name is specified, each entry printed is tagged by 
the name of the file from which it was extracted, using the format 
"filenameistring." 

EXAMPLES 

mcs -p file # Print file's comment section. 



FILES 



mcs -a string file # Append string to file's comment section 



TMPDJjR/mcs* temporary files 

TMPDIR/* temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environ- 
ment variable TMPDIR [see tempnamQ in tmpnam{3S)]. 

SEE ALSO 

cpp(l), a.out(4). 
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NOTES 

The mcs command cannot add new sections or delete existing sections 
executable objects with magic number 0413 [see a.o«f(4)]. 
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NAME 

mkshlib - create a shared library 
SYNOPSIS 

mkshlib -s specfil -t target [-h host] [-n] [-L dir ...] [-q] 
DESCRIPTION 

mkshlib builds both the host and target shared libraries. A shared library is 
similar in function to a normal, non-shared library, except that programs 
that link with a shared library will share the library code during execution, 
whereas programs that link with a non-shared library will get their own 
copy of each library routine used. 

The host shared library is an archive that is used to link-edit user programs 
with the shared library [see flr(4)]. A host shared library can be treated 
exactly like a non-shared library and should be included on cc(l) command 
lines in the usual way [see cc(l)]. Further, all operations that can be per- 
formed on an archive can also be performed on the host shared library. 

The target shared library is an executable module that is bound into the 
user's address space during execution of a program using the shared library. 
The target shared library contains the code for all the routines in the library 
and must be fully resolved. The target will be brought into memory during 
execution of a program using the shared library, and subsequent processes 
that use the shared library \^dll share the copy of code already in memory. 
The text of the target is always shared, but each process will get its own 
copy of the data. 

The user interface to mkshlib consists of command line options and a shared 
library specification file. The shared library specification file describes the 
contents of the shared library. 

The mkshlib command invokes other tools such as the archiver, ar{l), the 
assembler, fls(l), and the link editor, ld{l). Tools are invoked through the 
use of execvp [see exec{2)l which searches directories in the user's PATH. 
Also, prefixes to mkshlib are passed in the same manner as prefixes to the 
cc(l) command, and invoked tools are given the prefix, where appropriate. 
For example, i386mkshlib will invoke i386ld. 

The foUov^ng command line options are recognized by mkshlib: 

-8 specfil Specifies the shared library specification file, specfil. This file 
contains the information necessary to build a shared library. 
Its contents include the branch table specifications for the tar- 
get, the path name in which the target should be installed, the 
start addresses of text and data for the target, the initialization 
specifications for the host, and the list of object files to be 
included in the shared library (see details below). 

-t target Specifies the output filename of the target shared library being 
created. It is assumed that this file will be installed on the tar- 
get machine at the location given in the specification file (see 
the #target directive below). If the -n option is used, then a 
new target shared library will not be generated. 
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-h host Specifies the output filename of the host shared library being 
created. If this option is not given, then the host shared 
library will not be produced. 

-n Do not generate a nevy^ target shared library. This option is 

useful when producing only a new host shared library. The -t 
option must still be supplied since a version of the target 
shared library is needed to build the host shared library. 

-L dir ... Change the algorithm of searching for the host shared libraries 
specified with the #objects noload directive to look in dir 
before looking in the default directories. The -L option can be 
specified multiple times on the command line in which case 
the directories given v^th the -L options are searched in the 
order given on the command line before the default directories. 

-q Quiet warning messages. This option is useful when warning 

messages are expected but not desired. 

The shared library specification file contains all the information necessary to 
build both the host and target shared libraries. The contents and format of 
the specification file are given by the directives listed below. 

All directives that can be followed by multi-line specifications are valid until 
the next directive or the end of the file. 

#address sectname address 

Specifies the start address, address, of section sectname for the 
target. This directive typically is used to specify the start 
addresses of the .text and .data sections. One #address per 
section name is valid. A #address directive must be given 
exactly once for the .text section and once for the .data sec- 
tion. See the table in the section "The Building Process" in 
the "Shared Libraries" chapter of the UNIX System V 
Programmer's Guide for standard addresses. 

#target pathname 

Specifies the absolute path name, pathname, at which the tar- 
get shared library will be installed on the target machine. The 
operating system uses this path name to locate the shared 
library when executing a.out files that use this shared library. 
This directive must be specified exactly once per specification 
file. 

#branch 

Specifies the start of the branch table specifications. The lines 
foUovdng this directive are taken to be branch table specifica- 
tion lines. 

Branch table specification lines have the following format: 

funcname <white space> position 

where funcname is the name of the symbol given a branch 
table entry and position specifies the position of funcname's 
branch table entry, position may be a single integer or a range 
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of integers of the form positionl-positionl. Each position must 
be greater than or equal to one, the same position can not be 
specified more than once, and every position, from one to the 
highest given position, must be accounted for. 

If a symbol is given more than one branch table entry by asso- 
ciating a range of positions with the symbol or by specifying 
the same symbol on more than one branch table specification 
line, then the sjonbol is defined to have the address of the 
highest associated branch table entry. All other branch table 
entries for the symbol can be thought of as "empty" slots and 
can be replaced by nev^ entries in future versions of the shared 
library. Only functions should be given branch table entries, 
and those functions must be external symbols. 

This directive must be specified exactly once per shared library 
specification file. 

#objects 

The lines foUov^ng this directive are taken to be the list of 
input object files in the order they are to be loaded into the 
target. The list simply consists of each path name followed by 
a newline character. This list is also used to determine the 
input object files for the host shared library, but the order for 
the host is given by running the list through lorder(l) and 
tsort{iy 

This directive must be specified exactly once per shared library 
specification file. 

#objects noload 

The #objects noload is followed by a list of host shared 
libraries. These libraries are searched in the order listed to 
resolve undefined symbols from the library being built. Dur- 
ing the search it is considered an error if a non-shared version 
of a s)mibol is found before a shared version of the symbol. 

Each name given is assumed to be a path name to a host or an 
argument of the form -IX, where libX.a is the name of a file in 
LIBDIR or LLIBDIR. This behavior is identical to that of Id, 
and the -L option can be used on the command line to specify 
other directories in which to locate these archives. 

Note that if a host shared library is specified using #objects 
noload, any cc command that links to the shared library being 
built v^l need to specify that host also. 

#hide linker [*] 

This directive changes symbols that are normally external into 
static symbols, local to the library being created. A regular 
expression may be given [sh(l), find(l)], in which case all 
external symbols matching the regular expression are hidden; 
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the #export directive (see below) can be used to counter this 
effect for specified symbols. 

The optional "*" is equivalent to the directive 
#hide linker 

and causes all external symbols to be made into static sym- 
bols. 

All symbols specified in #init and #branch directives are 
assumed to be external symbols, and cannot be changed into 
static symbols using the #hide directive. 

#export linker [*] 

Symbols given in the #export directive are external symbols 
(global among files) that, because of a regular expression in a 
#hide directive, would otherwise have been made static. For 
example, 

#hide linker * 
#export linker 

one 

two 

causes all symbols except one, two, and those used in #branch 
and #init entries to be tagged as static. 

#init object 

Specifies that the object file, object, requires initialization code. 
The lines following this directive are taken to be initialization 
specification lines. 

Initialization specification lines have the following format: 

ptr <white space> import 

ptr is a pointer to the associated imported symbol, import, and 
must be defined in the current specified object file, object. The 
initialization code generated for each such line is of the form: 

ptr = &import; 

All initializations for a particular object file must be given once 
and multiple specifications of the same object file are not 
allowed. 

#ident string 

Specifies a string, string, to be included in the .comment sec- 
tion of the target shared library. 

## 

Specifies a comment. All information on the line beginning 
with ## is ignored. 
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FILES 

TEMPDIR/* temporary fUes 

TEMPDIR is usually /usr/tmp but can be redefined by setting the environ- 
ment variable TMPDIR [see tempnamQ in tmpnam(3S)]. 

LIBDIR usuaUy /lib 

LLIBDIR usually /usr/lib 

SEE ALSO 

ar(l), as(l), cc(l), chkshlib(l), ld(l), lorder(l), tsort(l), a.out(4), ar(4). 
"Shared Libraries" chapter in the UNIX System V Programmer's Guide. 
CAVEATS 

The -n option cannot be used vydth the #objects noload directive. 

If mkshlib is asked to create a host library and a host of that name already 
exists, mkshlib wHl update the host using ar -ru. This means that you 
should alv^ays remove the host before rebuilding whenever an object file 
previously included in the library is removed or renamed. 

If the address specified with the #address directive is outside user space, 
the library build may look successful, but if you try to use it, it might not 
work. 
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NAME 

nm - print name list of common object file 

SYNOPSIS 

nm [-oxhvnefurpVT] file name ... 

DESCRIPTION 

The nm command displays the symbol table of each common object file, 
filename. Filename may be a relocatable or absolute common object file; or 
it may be an archive of relocatable or absolute common object files. For 
each s)niibol, the following information will be printed: 

Name The name of the s)niibol. 

Value Its value expressed as an offset or an address depending on its 
storage class. 

Class Its storage class. 

Type Its type and derived type. If the symbol is an instance of a struc- 
ture or of a union, then the structure or union tag will be given 
following the type (e.g., struct-tag). If the symbol is an array, 
then the array dimensions will be given following the type (e.g., 
char[ n ][ m ] ). Note that the object file must have been compiled 
with the -g option of the cc(l) command for this information to 
appear. 

Size Its size in bytes, if available. Note that the object file must have 
been compiled with the -g option of the cc(l) command for this 
information to appear. 

Line The source line number at which it is defined, if available. Note 
that the object file must have been compiled with the -g option of 
the cc(l) command for this information to appear. 

Section For storage classes static and external, the object file section con- 
taining the symbol (e.g., text, data, or bss). 

The output of nm may be controlled using the following options: 
-o Print the value and size of a symbol in octal instead of decimal. 

-X Print the value and size of a symbol in hexadecimal instead of 

decimal. 

-h Do not display the output header data. 

-V Sort external symbols by value before they are printed, 

-n Sort external s)nnbols by name before they are printed, 

-e Print only external and static symbols. 

-f Produce full output. Print redundant symbols (.text, .data, .lib, 

and .bss), normally suppressed. 

-u Print undefined symbols only. 

-r Prepend the name of the object file or archive to each output line. 
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-p Produce easily parsable, terse output. Each symbol name is pre- 

ceded by its value (blanks if undefined) and one of the letters U 
(undefined), A (absolute), T (text segment symbol), D (data seg- 
ment symbol), S (user-defined segment symbol), R (register sym- 
bol), F (file symbol), or C (common symbol). If the symbol is 
local (non-external), the type letter is in lowercase. 

-V Print the version of the nm command executing on the standard 

error output. 

-T By default, nm prints the entire name of the symbols listed. Since 

object files can have S5mcibols names with an arbitrary number of 
characters, a name that is longer than the width of the column set 
aside for names vdll overflow its column, forcing every column 
after the name to be misaligned. The -T option causes nm to 
truncate every name which would othervydse overflow its column 
and place an asterisk as the last character in the displayed name 
to mark it as truncated. 

Options may be used in any order, either singly or in combination, and may 
appear an)rwhere in the command line. Therefore, both nm name -e -v 
and nm -ve name print the static and external symbols in name, with exter- 
nal symbols sorted by value. 

FILES 

TMPDIR/* temporary fUes 

TMPDIR is usually /usr/tmp but can be redefined by setting the environ- 
ment variable TMPDIR [see tempnamO in tmpnam{3S)]. 

SEE ALSO 

as(l), cc(l), ld(l), tmpnam(3S), a.out(4), ar(4). 

DIAGNOSTICS 

"nm: name: cannot open" 

if name cannot be read. 

"nm: name: bad magic" 

if name is not a common object file. 

"nm: name: no symbols" 

if the symbols have been stripped from name, 

BUGS 

When all the symbols are printed, they must be printed in the order they 
appear in the symbol table in order to preserve scoping information. There- 
fore, the -V and -n options should be used only in conjunction v^th the -e 
option. 
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NAME 

prof - display profile data 
SYNOPSIS 

prof [-tcan] [-ox] [-g] [-z] [-h] [-s] [-m mdata] [prog] 
DESCRIPTION 

The prof command interprets a profile file produced by the monitor{3C) 
function. The symbol table in the object file prog (a.out by default) is read 
and correlated with a profile file (mon.out by default). For each external 
text symbol the percentage of time spent executing between the address of 
that symbol and the address of the next is printed, together with the 
number of times that function was called and the average number of mil- 
liseconds per call. 

The mutually exclusive options i, c, a, and n determine the type of sorting 
of the output lines: 

-t Sort by decreasing percentage of total time (default), 
-c Sort by decreasing number of calls, 
-a Sort by increasing symbol address, 
-n Sort lexically by symbol name. 

The mutually exclusive options o and x specify the printing of the address 
of each symbol monitored: 

-o Print each symbol address (in octal) along with the symbol name. 

-X Print each symbol address (in hexadecimal) along with the symbol 
name. 

following options may be used in any combination: 
Include non-global symbols (static functions). 

Include all symbols in the profile range [see monitor{3C)l even if 
associated with zero number of calls and zero time. 

Suppress the heading normally printed on the report. (This is use- 
ful if the report is to be processed further.) 

Print a summary of several of the monitoring parameters and statis- 
tics on the standard error output. 

-m mdata 

Use file mdata instead of mon.out as the input profile file. 

A program creates a profile file if it has been loaded with the -p option of 
cc(l). This option to the cc command arranges for calls to monitor (3C) at 
the beginning and end of execution. It is the call to monitor at the end of 
execution that causes a profile file to be written. The number of calls to a 
function is tallied if the -p option was used when the file containing the 
function was compiled. 

The name of the file created by a profiled program is controlled by the 
environment variable PROFDIR. If PROFDIR does not exist, "mon.out" is 
produced in the directory that is current when the program terminates. If 
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PROFDIR = string, "string/pid.progname" is produced, where progname con- 
sists of argv[0] with any path prefix removed, and pid is the program's pro- 
cess id. If PROFDIR is the null string, no profiling output is produced. 

A single function may be split into subfunctions for profiling by means of 
the MARK macro [see prof{5)]. 

HLES 

mon.out for profile 
a.out for namelist 

SEE ALSO 

cc(l), exit(2), profil(2), monitor(3C), prof(5). 
WARNING 

The times reported in successive identical runs may show variances of 20% 
or more, because of var)dng cache-hit ratios due to sharing of the cache 
with other processes. Even if a program seems to be the only one using the 
machine, hidden background or asynchronous processes may blur the data. 
In rare cases, the clock ticks initiating recording of the program counter may 
"beat" with loops in a program, grossly distorting measurements. 

Call counts are always recorded precisely. 

The times for static functions are attributed to the preceding external text 
symbol if the -g option is not used. However, the call counts for the 
preceding function are still correct, i.e., the static function call counts are not 
added in with the call counts of the external function. 

CAVEATS 

Only programs that call exit{2) or return from main will cause a profile file 
to be produced, unless a final call to monitor is explicitly coded. 

The use of the -p option to cc(l) to invoke profiling imposes a limit of 600 
functions that may have call counters established during program execution. 
For more counters you must call monitor{3C) directly. If this limit is 
exceeded, other data will be overvmtten and the mon.out file will be cor- 
rupted. The number of call counters used will be reported automatically by 
the prof command whenever the number exceeds 5/6 of the maximum. 
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NAME 

prs - print an SCCS file 
SYNOPSIS 

prs [-d[dataspec]] [-r[SID]] [-e] [-1] [-c[date-time]] [-a] files 
DESCRIPTION 

The prs command prints, on the standard output, parts or all of an SCCS file 
[see sccsfile(4)] in a user-supplied format. If a directory is named, prs 
behaves as though each file in the directory were specified as a named file, 
except that non-SCCS files (last component of the path name does not begin 
with s.) and unreadable files are silently ignored. If a name of - is given, 
the standard input is read; each line of the standard input is taken to be the 
name of an SCCS file or directory to be processed; non-SCCS files and 
unreadable files are silently ignored. 

Arguments to prs, which may appear in any order, consist of keyletter argu- 
ments and file names. 

All the described keyletter arguments apply independently to each named 
fUe: 

-dldataspec] Used to specify the output data specification. The 
dataspec is a string consisting of SCCS file data key- 
words (see DATA KEYWORDS) interspersed with 
optional user-supplied text. 

-T[SID] Used to specify the SCCS Identification (SID) string of 

a delta for which information is desired. If no SID is 
specified, the SID of the most recently created delta is 
assumed. 

Requests information for all deltas created earlier than 
and including the delta designated via the -r keyletter 
or the date given by the -c option. 

Requests information for all deltas created later than 
and including the delta designated via the -r keyletter 
or the date given by the -c option. 

The cutoff date-time -c[cutoff] is in the form: 

YY[MM[DD[HH[MM[SS]]]]] 

Units omitted from the date-time default to their max- 
imum possible values; that is, -c7502 is equivalent to 
-C750228235959. Any number of non-numeric charac- 
ters may separate the various 2-digit pieces of the cut- 
off date in the form: " -c77/2/2 9:22:25 " . 

-a Requests printing of information for both removed, 

i.e., delta tjrpe = R, [see rmdel{\)\ and existing, i.e., 
delta type = D, deltas. If the -a keyletter is not speci- 
fied, information for existing deltas only is provided. 



-1 

-cfdate-time] 



- 1 - 



PRS(l) 



(C Software Development Set) 



PRS(l) 



DATA KEYWORDS 

Data keywords specify which parts of an SCCS file are to be retrieved and 
output. All parts of an SCCS file [see sccsfile{4)] have an associated data 
keyword. There is no limit on the number of times a data keyword may 
appear in a dataspec. 

The information printed by prs consists of: (1) the user-supplied text; and 
(2) appropriate values (extracted from the SCCS file) substituted for the 
recognized data keywords in the order of appearance in the dataspec. The 
format of a data keyword value is either Simple (S), in which keyword sub- 
stitution is direct, or Multiline (M), in which keyword substitution is fol- 
lowed by a carriage return. 

User-supplied text is any text other than recognized data keywords. 

A tab is specified by \t and carriage retum/new-line is specified by \n. 

The default data keywords are: 

" :Dt:\t:DL:\nMRs:\n:MR:COMMENTS:\n:C: " 
TABLE 1. SCCS Files Data Keywords 





L/UlU item 


File Section 


Value 


FoTtnat 


:Dt: 


Delta information 


Delta Table 




5 


:DL: 


Delta line statistics 


tl 


:Li:/:Ld:/:Lu: 


S 


:Li: 


Lines inserted by Delta 




nnnnn 


S 


:Ld: 


Lines deleted by Delta 


II 


nnnnn 


S 


:Lu: 


Lines unchanged by Delta 


II 


nnnnn 


S 


:DT: 


Delta type 


II 


D'or'R 


S 


:I: 


SCCS ID string (SID) 


tl 


:R:.:L:.:B:.:S: 


S 


:R: 


Release number 


II 


nnnn 


S 


:L: 


Level number 


II 


nnnn 


S 


:B: 


Branch number 


tl 


nnnn 


S 


:S: 


Sequence number 


II 


nnnn 


S 


:D: 


Date Delta created 




:Dy:/:Dm:/:Dd: 


S 


:Dy: 


Year Delta created 


II 


nn 


S 


:Dm: 


Month Delta created 


tl 


nn 


s 


:Dd: 


Day Delta created 


It 


nn 


s 


:T: 


Time Delta created 


It 


:Th:::Tm:::Ts: 


s 


:Th: 


Hour Delta created 


It 


nn 


s 


:Tm: 


Minutes Delta created 


It 


nn 


s 


:Ts: 


Seconds Delta created 


It 


nn 


s 


:P: 


Programmer who created Delta 


II 


logname 


s 


:DS: 


Delta sequence number 




nnnn 


s 


:DP: 


Predecessor Delta seq-no. 




nnnn 


s 


:DI: 


Seq-no. of deltas incl., excl., ignored 


It 


:Dn:/:Dx:/:Dg: 


s 


:Dn: 


Deltas included (seq #) 




:DSr:DS:... 


s 


:Dx: 


Deltas excluded (seq #) 


tl 


:DS:-:DS:... 


s 


:Dg: 


Deltas ignored (seq #) 




:DSr:DS:... 


s 


:MR: 


MR numbers for delta 


II 


text 


M 


:C: 


Comments for delta 


II 


text 


M 


:UN: 


User names 


User Names 


text 


M 


:FL: 


Flag list 


Flags 


text 


M 


:Y: 


Modide type flag 


It 


text 


s 


:MF: 


MR validation flag 


It 


yes'ot'no 


s 
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TABLE 1. sees Files Data Keywords (continued) 



Keyword 


Data Item 


File Section 


Value 


Format 


:MP: 


MR validation pgm name 


II 


text 


S 


:KF: 


Keyword error /warning flag 




yes" or" no 


S 


:KV: 


Keyword validation string 




text 




:BF: 


Branch flag 




yes"ox"no 


S 


:J: 


Joint edit flag 




yes"or"no 


S 


:LK: 


Locked releases 




:R:... 


S 


:Q: 


User-deflned keyword 




text 


S 


:M: 


Module name 




text 


S 


.CD. 

:rD: 


Floor boundary 




•i\.> 


c 


:CB: 


Ceiling boundary 




:R: 


S 


rDs: 


Default SID 




:I: 


s 


:ND: 


Null delta flag 




yes" or" no 


s 


:FD: 


File descriptive text 


Comments 


text 


M 


:BD: 


Body 


Body 


text 


M 


:GB: 


Gotten body 


II 


text 


M 


:W: 


A form of what{l) string 


N/A 


:Z::M:\t:I: 


S 


:A: 


A form of whatH) string 


N/A 


Z::Y:-:M:-:I::Z 


: S 


:Z: 


whatiD string delimiter 


N/A 


@(#) 


S 


:F: 


sees file name 


N/A 


text 


S 


:PN: 


sees file path name 


N/A 


text 


S 




* :Dtr=":DTf:I:-:Dr:Tr:Pr:DS:-:DP: 









EXAMPLES 

prs -d" Users and/or user IDs for :F: are:\n:UN:" s.file 

may produce on the standard output: 

Users and/or user IDs for s.file are: 

xyz 

131 

abc 

prs -d"Nev^est delta for pgm :M:: :I: Created :D: By :?:" -r s.file 
may produce on the standard output: 

Newest deha for pgm main.c: 3.7 Created 77/12/1 By cas 
As a special case: 

prs s.file 

may produce on the standard output: 

D 1.1 77/\l/\ 00:00:00 cas 1 000000/00000/00000 
MRs: 

bl78-12345 
bl79-54321 
COMMENTS: 

this is the comment line for s.file initial delta 

for each delta table entry of the "D" type. The only keyletter argument 
allowed to be used with the special case is the -a keyletter. 
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FILES 

/tmp/pr????? 

SEE ALSO 

admin(l), delta(l), get(l), sccsfae(4). 
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NAME 

regcmp - regular expression compile 

SYNOPSIS 

regcmp [ - ] files 

DESCRIPTION 

The regcmp command performs a function similar to regcmp {3X) and, in 
most cases, precludes the need for calling regcmp (3X) from C programs. 
This saves on both execution time and program size. The command regcmp 
compiles the regular expressions in file and places the output in fileA. If the 
- option is used, the output will be placed in file.c. The format of entries in 
file is a name (C variable) followed by one or more blanks followed by a 
regular expression enclosed in double quotes. The output of regcmp is C 
source code. Compiled regular expressions are represented as extern char 
vectors. FileA files may thus be included in C programs, or file.c files may 
be compiled and later loaded. In the C program which uses the regcmp out- 
put, regex(abc ,line) will apply the regular expression named abc to line. 
Diagnostics are sellF-explanatory. 

EXAMPLES 

name " ([A-Za-z][A-Za-zO-9_]*)$0 " 

telno "\({0,1}([2-9][01][1-9])$0\){0,1} *" 
"([2-9][0-9]{2})$l[-]{0,l}" 
"([0-9]{4})$2" 

In the C program that uses the regcmp output, 

regex(telno, line, area, exch, rest) 

will apply the regular expression named telno to line, 

SEE ALSO 

regcmp(3X). 
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NAME 

rmdel - remove a delta from an SCCS file 

SYNOPSIS 

rmdel -rSID files 

DESCRIPTION 

The rmdel command removes the delta specified by the SID from each 
named SCCS file. The delta to be removed must be the nev^est (most 
recent) delta in its branch in the delta chain of each named SCCS file. In 
addition, the delta specified must not be that of a version being edited for 
the purpose of making a delta (i. e., if a p-file [see get{l)] exists for the 
named SCCS file, the delta specified must not appear in any entry of the p- 
file). 

The -r option is used for specifying the SID (SCCS IDentification) level of 
the delta to be removed. 

If a directory is named, rmdel behaves as though each file in the directory 
were specified as a named file, except that non-SCCS files (last component 
of the path name does not begin vdth s.) and unreadable files are silently 
ignored. If a name of - is given, the standard input is read; each line of the 
standard input is taken to be the name of an SCCS file to be processed; 
non-SCCS files and unreadable files are silently ignored. 

Simply stated, the rules are: 

(1) if you make a delta, you can remove it. 
or 

(2) if you ov^n the file and directory, you can remove a delta. 

FILES 

x.file [see delta{l)] 
z.file [see delta{l)] 

SEE ALSO 

delta(l), get(l), prs(l), sccsfile(4). 
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NAME 

sact - print current SCCS file editing activity 

SYNOPSIS 

sact files 

DESCRIPTION 

The sact command informs the user of any impending deltas to a named 
SCCS file. This situation occurs when get{l) with the -e option has been 
previously executed without a subsequent execution of delta(l). If a direc- 
tory is named on the command line, sact behaves as though each file in the 
directory were specified as a named file, except that non-SCCS files and 
unreadable files are silently ignored. If a name of - is given, the standard 
input is read with each line being taken as the name of an SCCS file to be 
processed. 

The output for each named file consists of five fields separated by spaces. 



Field 1 



Field 2 



Field 4 



Field 3 



Field 5 



specifies the SID of a delta that currently exists in the 
SCCS file to which changes will be made to make the 
new delta. 

specifies the SID for the new delta to be created. 

contains the logname of the user who will make the delta 
(i.e., executed a get for editing). 

contains the date that get -e was executed. 

contains the time that get -e was executed. 



SEE ALSO 



delta(l), get(l), unget(l). 
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NAME 

sccsdiff - compare two versions of an SCCS file 

SYNOPSIS 

sccsdiff -rSIDl -rSID2 [-p] [-sn] files 

DESCRIPTION 

The sccsdiff command compares two versions of an SCCS file and generates 
the differences between the two versions. Any number of SCCS files may 
be specified, but arguments apply to all files. 

-rSID? SIDl and SID2 specify the deltas of an SCCS file that are 

to be compared. Versions are passed to bdiff(l) in the 
order given. 

-p pipe output for each file through pr{l). 

-8" n is the file segment size that bdiff will pass to diff{l). 

This is useful when diff fails due to a high system load. 

FILES 

/tmp/get????? Temporary files 

SEE ALSO 

get(l). 

bdiff(l), pr(l) in the User's/System Administrator's Reference Manual 
DIAGNOSTICS 

"/f/e: No differences" If the two versions are the same. 
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NAME 

sdb - symbolic debugger 
SYNOPSIS 

sdb [-W] [-W] [objfil [corfil [directory-list]]] 
DESCRIPTION 

The sdh command calls a symbolic debugger that can be used with C pro- 
grams. It may be used to examine their object files and core files and to 
provide a controlled environment for their execution, 

Objfil is an executable program file which has been compiled with the -g 
(debug) option. If it has not been compiled with the -g option, the sym- 
bolic capabilities of sdb will be limited, but the file can still be examined and 
the program debugged. The default for objfil is a.out. Corfil is assumed to 
be a core image file produced after executing objfil; the default for corfil is 
core. The core file need not be present. A - in place of corfil will force sdb 
to ignore any core image file. The colon-separated list of directories 
(directory-list) is used to locate the source files used to build objfiL 

It is useful to know that at any time there is a current line and current file. 
If corfil exists, then they are initially set to the line and file containing the 
source statement at which the process terminated. Otherwise, they are set 
to the first line in main{). The current line and file may be changed with 
the source file examination commands. 

By default, warnings are provided if the source files used in producing objfil 
cannot be found, or are newer than objfil. This checking feature and the 
accompanying warnings may be disabled by the use of the -W flag. 

Names of variables are written just as they are in C. sdb does not truncate 
names. Variables local to a procedure may be accessed using the form 
procedure '.variable. If no procedure name is given, the procedure containing 
the current line is used by default. 

It is also possible to refer to structure members as variable. member, pointers 
to structure members as variable->member, and array elements as 
variable[number]. Pointers may be dereferenced by using the form 
pointer[0]. Combinations of these forms may also be used. A number may 
be used in place of a structure variable name, in which case the number is 
viewed as the address of the structure, and the template used for the struc- 
ture is that of the last structure referenced by sdb. An unqualified structure 
variable may also be used with various commands. Generally, sdb will 
interpret a structure as a set of variables. Thus, sdb will display the values 
of all the elements of a structure when it is requested to display a structure. 
An exception to this interpretation occurs when displaying variable 
addresses. An entire structure does have an address, and it is this value sdb 
displays, not the addresses of individual elements. 

Elements of a multidimensional array may be referenced as variable 
[number][number] . . . , or as variable [number, number, ...]. In place of number, 
the form number;number may be used to indicate a range of values, * may 
be used to indicate all legitimate values for that subscript, or subscripts may 
be omitted entirely if they are the last subscripts and the full range of values 
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is desired. As with structures, sdb displays all the values of an array or of 
the section of an array if trailing subscripts are omitted. It displays only the 
address of the array itself or of the section specified by the user if subscripts 
are omitted. 

A particular instance of a variable on the stack may be referenced by using 
the form procedure -.variable, number. All the variations mentioned in naming 
variables may be used. Number is the occurrence of the specified procedure 
on the stack, counting the top, or most current, as the first. If no procedure 
is specified, the procedure currently executing is used by default. 

It is also possible to specify a variable by its address. All forms of integer 
constants which are valid in C may be used, so that addresses may be input 
in decimal, octal, or hexadecimal. 

Line numbers in the source program are referred to as file-name '.number or 
procedure '.number. In either case the number is relative to the beginning of 
the file. If no procedure or file name is given, the current file is used by 
default. If no number is given, the first line of the named procedure or file 
is used. 

While a process is running under sdb, all addresses refer to the executing 
program; otherwise they refer to objfil or corfil. An initial argument of -w 
permits overwriting locations in objfil. 

Addresses 

The address in a file associated with a written address is determined by a 
mapping associated with that file. Each mapping is represented by two tri- 
ples (bl, el, fl) and {b2, el, f2) and the file address corresponding to a writ- 
ten address is calculated as follows: 

bl ^address <el 
then 

file address=address+fl-bl 

otherwise 

b2:^address<e2 
then 

file address=address+f2-b2 

otherwise, the requested address is not legal. In some cases (e.g., for pro- 
grams with separated I and D space) the two segments for a file may over- 
lap. 

The initial setting of both mappings is suitable for normal a.out and core 
files. If either file is not of the kind expected, then, for that file, bl is set to 
0, el is set to the maximum file size, and fl is set to 0; in this way the 
whole file can be examined with no address translation. 

In order for sdb to be used on large files, all appropriate values are kept as 
signed 32-bit integers. 
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Commands 

The commands for examining data in the program are: 
t Print a stack trace of the terminated or halted program. 
T Print the top line of the stack trace. 
variable /elm 

Print the value of variable according to length / and format m. A 
numeric count c indicates that a region of memory, beginning at the 
address implied by variable, is to be displayed. The length specifiers 
are: 

b one byte 

h two bytes (half word) 

1 four bytes (long word) 

Legal values for m are: 

c character 

d decimal 

u decimal, unsigned 

octal 

X hexadecimal 

f 32-bit single precision floating point 

g 64-bit double precision floating point 

s Assume variable is a string pointer and print characters 

starting at the address pointed to by the variable, 
a Print characters starting at the variable's address. This 

format may not be used with register variables, 
p pointer to procedure 

1 disassemble machine-language instruction with 
addresses printed numerically and symbolically. 

I disassemble machine-language instruction with 

addresses just printed numerically. 

Length specifiers are only effective with the c, d, u, o, and x formats. 
Any of the specifiers, c, /, and m, may be omitted. If all are omitted, 
sdb chooses a length and a format suitable for the variable's type as 
declared in the program. If m is specified, then this format is used for 
displa)dng the variable. A length specifier determines the output 
length of the value to be displayed, sometimes resulting in truncation. 
A count specifier c tells sdb to display that many units of memory, 
beginning at the address of variable. The number of bytes in one such 
unit of memory is determined by the length specifier /, or if no length 
is given, by the size associated with the variable. If a count specifier is 
used for the s or a command, then that many characters are printed. 
Otherwise successive characters are printed until either a null byte is 
reached or 128 characters are printed. The last variable may be 
redisplayed with the command ./. 

The sh(l) metacharacters * and ? may be used within procedure and 
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variable names, providing a limited form of pattern matching. If no 
procedure name is given, variables local to the current procedure and 
global variables are matched; if a procedure name is specified, then 
only variables local to that procedure are matched. To match only 
global variables, the form ipattem is used. 

linenumher?lm 
variahleillm 

Print the value at the address from a.out or I space given by 
linenumber or variable (procedure name), according to the format Im. 
The default format is 'i'. 

variable =lm 
linenumber =lm 
number=lm 

Print the address of variable or linenumber, or the value of number, in 
the format specified by Im. If no format is given, then Ix is used. The 
last variant of this command provides a convenient way to convert 
between decimal, octal, and hexadecimal. 

variablelvalue 

Set variable to the given value. The value may be a number, a charac- 
ter constant, or a variable. The value must be well defined; expres- 
sions which produce more than one value, such as structures, are not 
allowed. Character constants are denoted 'character. Numbers are 
viewed as integers unless a decimal point or exponent is used. In this 
case, they are treated as having the type double. Registers are viewed 
as integers. The variable may be an expression which indicates more 
than one variable, such as an array or structure name. If the address 
of a variable is given, it is regarded as the address of a variable of type 
int, C conventions are used in any type conversions necessary to per- 
form the indicated assignment. 

X Print the machine registers and the current machine-language instruc- 
tion. 

X Print the current machine-language instruction. 
The commands for examining source files are: 

e procedure 

e file-name 

e directory/ 

e directory file-name 

The first two forms set the current file to the file containing procedure 
or to file-name. The current line is set to the first line in the named 
procedure or file. Source files are assumed to be in directory. The 
default is the current working directory. The latter two forms change 
the value of directory. If no procedure, file name, or directory is given, 
the current procedure name and file name are reported. 
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/regular expression / 

Search forward from the current line for a line containing a string 
matching regular expression as in ed{l). The trailing / may be deleted. 

Iregular expression! 

Search backward from the current line for a line containing a string 
matching regular expression as in ed{\). The trailing ? may be deleted. 

p Print the current line. 

z Print the current line followed by the next 9 lines. Set the current line 
to the last line printed. 

w Window. Print the 10 lines around the current line. 

number 

Set the current line to the given line number. Print the new current 
line. 

counter 

Advance the current line by count lines. Print the new current line. 
count- 

Retreat the current line by count lines. Print the new current line. 

The commands for controlling the execution of the source program are: 

count r args 
count R 

Run the program v^th the given arguments. The r command with no 
arguments reuses the previous arguments to the program while the R 
command runs the program with no arguments. An argument begin- 
ning with < or > causes redirection for the standard input or output, 
respectively. If count is given, it specifies the number of breakpoints 
to be ignored. 

linenumber c count 

linenumber C count 

Continue after a breakpoint or interrupt. If count is given, the pro- 
gram vdll stop when count breakpoints have been encountered. The 
signal which caused the program to stop is reactivated with the C 
command and ignored with the c command. If a line number is speci- 
fied, then a temporary breakpoint is placed at the line and execution is 
continued. The breakpoint is deleted when the command finishes. 

linenumber g count 

Continue after a breakpoint v^th execution resumed at the given line. 
If count is given, it specifies the number of breakpoints to be ignored. 

s count 
S count 

Single-step the program through count lines. If no count is given, then 
the program is run for one line. S is equivalent to s except it steps 
through procedure calls. 
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i 

I Single-step by one machine-language instruction. The signal which 
caused the program to stop is reactivated with the I command and 
ignored with the i command. 

variable$m count 
addressm count 

Single-step (as with s) until the specified location is modified with a 
new value. If count is omitted, it is effectively infinity. Variable must 
be accessible from the current procedure. Since this command is done 
by software, it can be very slow. 

level V 

Toggle verbose mode, for use when single-stepping with S, s, or m. If 
level is omitted, then just the current source file and/or subroutine 
name is printed when either changes. If level is 1 or greater, each C 
source line is printed before it is executed; if level is 2 or greater, each 
assembler statement is also printed. A v turns verbose mode off if it is 
on for any level. 

k Kill the program being debugged. 

procedure(argl ,arg2, . . .) 

procedure(argl ,arg2, . . .)/m 

Execute the named procedure with the given arguments. Arguments 
can be integer, character, or string constants or names of variables 
accessible from the current procedure. The second form causes the 
value returned by the procedure to be printed according to format m. 
If no format is given, it defaults to d. This facility is only available if 
the program was loaded with the -g option. 

linenumber b commands 

Set a breakpoint at the given line. If a procedure name without a line 
number is given (e.g., "proc:"), a breakpoint is placed at the first line 
in the procedure even if it was not compiled with the -g option. If no 
linenumber is given, a breakpoint is placed at the current line. If no 
commands are given, execution stops just before the breakpoint and 
control is returned to sdb. Otherwise the commands are executed 
when the breakpoint is encountered and execution continues. Multi- 
ple commands are specified by separating them with semicolons. If k 
is used as a command to execute at a breakpoint, control returns to 
sdb, instead of continuing execution. 

B Print a list of the currently active breakpoints. 

linenumber d 

Delete a breakpoint at the given line. If no linenumber is given, then 
the breakpoints are deleted interactively. Each breakpoint location is 
printed and a line is read from the standard input. If the line begins 
with a y or d, then the breakpoint is deleted. 

D Delete all breakpoints. 

1 Print the last executed line. 
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linenumber a 

Announce. If linenumber is of the form procxnumber, the command 
effectively does a linenumber b 1. If linenumber is of the form proci, 
the command effectively does a procx b T. 

Miscellaneous commands: 

\command 

The command is interpreted by sfz(l). 

new-line 

If the previous command printed a source line, then advance the 
current line by one line and print the new current line. If the previous 
command displayed a memory location, then display the next memory 
location. 

end-of-file character 

Scroll. Print the next 10 lines of instructions, source or data depend- 
ing on which was printed last. The end-of-file character is usually 
control-D. 

< filename 

Read commands irom filename until the end of file is reached, and 
then continue to accept commands from standard input. When sdb is 
told to display a variable by a command in such a file, the variable 
name is displayed along with the value. This command may not be 
nested; < may not appear as a command in a file. 

M Print the address maps. 

M [?/] [*\bef 

Record new values for the address map. The arguments ? and / 
specify the text and data maps, respectively. The first segment (bl, el, 
fl) is changed unless * is specified; in which case, the second segment 
{bl, el, fl) of the mapping is changed. If fewer than three values are 
given, the remaining map parameters are left unchanged. 

" string 

Print the given string. The C escape sequences of the form \character 
are recognized, where character is a nonnumeric character. 

q Exit the debugger. 

The following commands also exist and are intended only for debugging the 
debugger: 

V Print the version number. 

Q Print a list of procedures and files being debugged. 

Y Toggle debug output. 

FILES 

a.out 
core 

SEE ALSO 

cc(l), a.out(4), core(4), syms(4). 
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sh(l) in the User's/System Administrator's Reference Manual. 
WARNINGS 

When sdb prints the value of an external variable for which there is no 
debugging information, a warning is printed before the value. The size is 
assumed to be int (integer). 

Data which are stored in text sections are indistinguishable from functions. 

Line number information in optimized functions is unreliable, and some 
information may be missing. 

BUGS 

If a procedure is called when the program is not stopped at a breakpoint 
(such as when a core image is being debugged), all variables are initialized 
before the procedure is started. This makes it impossible to use a procedure 
which formats data from a core image. 
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NAME 

size - print section sizes in bytes of common object files 

SYNOPSIS 

size [-n] [-f] [-o] [-x] [-V] files 

DESCRIPTION 

The size command produces section size information in bytes for each 
loaded section in the common object files. The size of the text, data, and 
bss (uninitialized data) sections is printed, as well as the sum of the sizes of 
these sections. If an archive file is input to the size command, the informa- 
tion for all archive members is displayed. 

The -n option includes NOLOAD sections in the size. 

The -f option produces full output, that is, it prints the size of every loaded 
section, followed by the section name in parentheses. 

Numbers will be printed in decimal unless either the -o or the -x option is 
used, in which case they will be printed in octal or in hexadecimal, respec- 
tively. 

The -V flag will supply the version information on the size command. 

SEE ALSO 

as(l), cc(l), ld(l), a.out(4), ar(4). 

DIAGNOSTICS 

size: name: cannot open 

if name cannot be read. 

size: name: bad magic 

if name is not an appropriate common object file. 

CAVEAT 

Since the size of bss sections is not known until link-edit time, the size com- 
mand will not give the true total size of pre-linked objects. 
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NAME 

strings - find the printable strings in an object file 

SYNOPSIS 

strings [-] [-o] [ -number ] file ... 

DESCRIPTION 

strings looks for ASCII strings in a binary file. A string is any sequence of 
four or more printing characters ending with a newline or a null character. 
Unless the - flag is given, strings only looks in the initialized data space of 
object files. If the -o flag is given, then each string is preceded by its 
decimal offset in the file. If the -number flag is given then number is used 
as the minimum string length rather than 4. 

strings is useful for identifying random object files and many other things. 
SEE ALSO 

hd(7), od(l) in the User's/System Administrator's Reference Manual. 

CREDIT 

This utility was developed at the University of California at Berkeley and is 
used with permission. 
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NAME 

strip - strip symbol and line number information from a common object file 

SYNOPSIS 

strip [-1] [-X] [-b] [-r] [-V] filename ... 

DESCRIPTION 

The strip command strips the symbol table and line number information 
from common object files, including archives. Once this has been done, no 
symbolic debugging access vdll be available for that file; therefore, this com- 
mand is normally run only on production modules that have been debugged 
and tested. 

The amount of information stripped from the symbol table can be controlled 
by using any of the foUov^ng options: 

-1 Strip line number information only; do not strip any symbol table 

information. 

-X Do not strip static or external symbol information. 

-b Same as the -x option, but also do not strip scoping information 

(e.g., beginning and end of block delimiters). 

-r Do not strip static or external symbol information, or relocation 

information. 

-V Print the version of the strip command executing on the standard 

error output. 

If there are any relocation entries in the object file and any symbol table 
information is to be stripped, strip will complain and terminate without 
stripping filename unless the -r option is used. 

If the strip command is executed on a common archive file [see flr(4)] the 
archive symbol table will be removed. The archive symbol table must be 
restored by executing the ar{l) command v^th the s option before the 
archive can be link-edited by the ld{l) command, strip will produce 
appropriate warning messages when this situation arises. 

The strip command is used to reduce the file storage overhead taken by the 
object file. 

FILES 

TMPD/jR/strp* temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environ- 
ment variable TMPDIR [see tempnami) in tmpnam{3S)]. 

SEE ALSO 

ar(l), as(l), cc(l), ld(l), tmpnam(3S), a.out{4), ar(4). 
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DIAGNOSTICS 

strip: name: cannot open if name cannot be read. 

strip: name: bad magic if name is not an appropriate common object 

file. 

strip: name: relocation entries present; cannot strip 

if name contains relocation entries and the -r 
flag is not used, the symbol table information 
cannot be stripped. 
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NAME 

tic - terminfo compiler 

SYNOPSIS 

tic [-v[n]] [-C] fUe 

DESCRIPTION 

tic translates a terminfo{4) file from the source format into the compiled for- 
mat. The results are placed in the directory /usr/ lib /terminfo. The com- 
piled format is necessary for use with the library routines described in 
curses{3X), 

-vn (verbose) output to standard error trace information showing he's 
progress. The optional integer n is a number from 1 to 10, 
inclusive, indicating the desired level of detail of information. If n 
is omitted, the default level is 1. If n is specified and greater than 
1, the level of detail is increased. 

-c only check file for errors. Errors in use= links are not detected. 

file contains one or more terminfo{A) terminal descriptions in source 
format [see terminfo{4)]. Each description in the file describes the 
capabilities of a particular terminal. When a VLS^^entry-name field 
is discovered in a terminal entry currently being compiled, tic reads 
in the binary from /usr /lib /terminfo to complete the entry. (Entries 
created from file will be used first. If the environment variable 
TERMINFO is set, that directory is searched instead of 
/usr /lib /terminfo,) tic duplicates the capabilities in entry-name for 
the current entry, with the exception of those capabilities that 
explicitly are defined in the current entry. 

If the environment variable TERMINFO is set, the compiled results are 
placed there instead of /usr /lib /terminfo, 

FILES 

/usr/lib/terminfo/?/* compiled terminal description data base 

SEE ALSO 

curses(3X), term(4), terminfo(4). 

Chapter 10 in the Programmer's Guide, 

DIAGNOSTICS 

Most diagnostic messages produced by tic during the compilation of the 
source file are preceded with the approximate line number and the name of 
the terminal currently being worked on. 

mkdir ... returned bad status 

The named directory could not be created. 

File does not start with terminal names in column one 

The first thing seen in the file, after comments, must be the list of 
terminal names. 

Token after a lseek{2) not NAMES 

Somehow the file being compiled changed during the compilation. 
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Not enough memory for use_Iist element 
or 

Out of memory 

Not enough free memory was available {malloc{3C) failed). 
Can't open ... 

The named file could not be created. 

Error in writing ... 

The named file could not be written to. 

Can't link ... to ... 

A link failed. 

Error in re-reading compiled file ... 

The compiled file could not be read back in. 

Premature EOF 

The current entry ended prematurely. 

Backspaced off beginning of line 

This error indicates something wrong happened within tic. 
Unknown Capability - 

The named invalid capability was found within the file. 
Wrong type used for capability 

For example, a string capability was given a numeric value. 
Unknown token type 

Tokens must be followed by '@' to cancel, '/ for booleans, '#' for 

numbers, or '=' for strings. 

bad term name 
or 

Line Illegal terminal name - 

Terminal names must start with a letter or digit 

The given name was invalid. Names must not contain white space 

or slashes, and must begin with a letter or digit. 

terminal name too long. 

An extremely long terminal name was found. 

terminal name too short. 

A one-letter name was found. 

filename too long, truncating to 

The given name was truncated to 14 characters due to UNIX file 
name length limitations. 

defined in more than one entry. Entry being used is 
An entry was found more than once. 

Terminal name synonym for itself 

A name was listed twice in the list of synonyms. 

At least one synonym should begin with a letter. 

At least one of the names of the terminal should begin with a 
letter. 
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Illegal character - 

The given invalid character was found in the input file. 

Newline in middle of terminal name 

The trailing comma was probably left off of the list of names. 

Missing comma 

A comma was missing. 

Missing numeric value 

The number was missing after a numeric capability. 

NULL string value 

The proper way to say that a string capability does not exist is to 
cancel it. 

Very long string found. Missing comma? 
self-explanatory 

Unknown option. Usage is: 

An invalid option was entered. 

Too many file names. Usage is: 
self-explanatory 

nonexistent or permission denied 

The given directory could not be written into. 

is not a directory 
self-explanatory 

"...": Permission denied 
access denied. 

"...": Not a directory 

tic wanted to use the given name as a directory, but it already 
exists as a file 

SYSTEM ERROR!! Fork failed!!! 
A fork{2) failed. 

Error in following up use-links. Either there is a loop in the links or they 
reference nonexistent terminals. The following is a list of the entries 
involved: 

A terminfo{4:) entry with a use=name capability either referenced a 
nonexistent terminal called name or name somehow referred back to 
the given entry. 

WARNING 

Total compiled entries cannot exceed 4096 bytes. The name field cannot 
exceed 128 bytes. 

Terminal names exceeding 14 characters will be truncated to 14 characters 
and a warning message will be printed. 

When the -c option is used, duplicate terminal names will not be diagnosed; 
however, when -c is not used, they will be. 
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BUGS 

To allow existing executables from the previous release of the UNIX System 
to continue to run with the compiled terminfo entries created by the new 
terminfo compiler, cancelled capabilities will not be marked as cancelled 
within the terminfo binary unless the entry name has a within it. (Such 
terminal names are only used for inclusion within other entries via a use= 
entry. Such names would not be used for real terminal names.) 

For example: 

4415+nl kfl@, kf2@, .... 

4415+base, kfl=\EOc, kf2=\EOd, .... 

4415-nll4415 terminal without keys, 
use=4415+nl, use=4415+base. 

The above example works as expected; the definitions for the keys do not 
show up in the 4415-nl entry. However, if the entry 4415+nl did not have 
a plus sign within its name, the cancellations would not be marked within 
the compiled file and the definitions for the function keys would not be 
cancelled within 4415-nl. 
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NAME 

tsort - topological sort 

SYNOPSIS 

tsort [file] 

DESCRIPTION 

The tsort command produces on the standard output a totally ordered list of 
items consistent with a partial ordering of items mentioned in the input file. 
If no file is specified, the standard input is understood. 

The input consists of pairs of items (nonempty strings) separated by blanks. 
Pairs of different items indicate ordering. Pairs of identical items indicate 
presence, but not ordering. 

SEE ALSO 

lorder(l). 

DIAGNOSTICS 

Odd data: there is an odd number of fields in the input file. 
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NAME 

unget - undo a previous get of an SCCS file 

SYNOPSIS 

unget [-rSID] [-s] [-n] files 

DESCRIPTION 

The unget command undoes the effect of a get -e done prior to creating the 
intended new delta. If a directory is named, unget behaves as though each 
file in the directory were specified as a named file, except that non-SCCS 
files and unreadable files are silently ignored. If a name of - is given, the 
standard input is read with each line being taken as the name of an SCCS 
file to be processed. 

Keyletter arguments apply independently to each named file. 



-rS/D 



Uniquely identifies which delta is no longer intended. 
(This would have been specified by get as the "new 
delta.") The use of this keyletter is necessary only if two 
or more outstanding gets for editing on the same SCCS 
file were done by the same person (login name). A diag- 
nostic results if the specified SID is ambiguous, or if it is 
necessary and omitted on the command line. 



-8 



Suppresses the printout, on the standard output, of the 
intended delta's SID. 



-n 



Causes the retention of the gotten file which would nor- 
mally be removed from the current directory. 



SEE ALSO 



delta(l), get(l), sact(l). 
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NAME 

val - validate SCCS file 

SYNOPSIS 

val - 

val [-s] [-rSID] [-mname] [-ytype] files 
DESCRIPTION 

The val command determines if the specified file is an SCCS file meeting the 
characteristics specified by the optional argument list. Arguments to val 
may appear in any order. The arguments consist of keyletter arguments, 
which begin with a and named files. 

The val command has a special argument, -, which causes reading of the 
standard input until an end-of-file condition is detected. Each line read is 
independently processed as if it were a command line argument list. 

The val command generates diagnostic messages on the standard output for 
each command line and file processed, and also returns a single 8-bit code 
upon exit as described below. 

The keyletter arguments are defined as follows. The effects of any keyletter 
argument apply independently to each named file on the command line. 

-s The presence of this argument silences the diagnostic message 

normally generated on the standard output for any error that is 
detected while processing each named file on a given com- 
mand line. 

-rSID The argument value SID (SCCS ID entification String) is an 

SCCS delta number. A check is made to determine if the SID 
is ambiguous (e.g., -rl is ambiguous because it physically does 
not exist but implies 1.1, 1.2, etc., which may exist) or invalid 
(e.g., -rl.O or -r 1.1.0 are invalid because neither case can exist 
as a valid delta number). If the SID is valid and not ambigu- 
ous, a check is made to determine if it actually exists. 

-mname The argument value name is compared with the SCCS %M% 
keyword in file. 

-ytype The argument value type is compared with the SCCS %Y% 
keyword in file. 

The 8-bit code returned by val is a disjunction of the possible errors, i. e., 
can be interpreted as a bit string where (moving from left to right) set bits 
are interpreted as follows: 

bit = missing file argument; 

bit 1 = unknown or duplicate keyletter argument; 

bit 2 = corrupted SCCS file; 

bit 3 = cannot open file or file not SCCS; 

bit 4 = SID is invalid or ambiguous; 

bit 5 = SID does not exist; 

bit 6 = %Y%, -y mismatch; 

bit 7 = %M%, -m mismatch; 
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Note that val can process two or more files on a given command line and in 
turn can process multiple command lines (when reading the standard input). 
In these cases an aggregate code is returned - a logical OR of the codes gen- 
erated for each command line and file processed. 

SEE ALSO 

admin(l), delta(l), get(l), prs(l). 

help(l) in the User's/System Administrator's Reference Manual 

DIAGNOSTICS 

Use help(l) for explanations. 

BUGS 

The val command can process up to 50 files on a single command line. 
Any number above 50 will produce a core dump. 
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NAME 

vc - version control 
SYNOPSIS 

vc [-a] [-t] [-cchar] [-s] [key word= value ... key word= value] 
DESCRIPTION 

The vc command copies lines from the standard input to the standard out- 
put under control of its arguments and control statements encountered in the 
standard input. In the process of perforraing the copy operation, user 
declared keywords may be replaced by their string value when they appear 
in plain text and/or control statements. 

The copying of lines from the standard input to the standard output is con- 
ditional, based on tests (in control statements) of heywoxd values specified 
in control statements or as vc command arguments. 

A control statement is a single line beginning with a control character, 
except as modified by the -t keyletter (see below). The default control char- 
acter is colon (:), except as modified by the -c keyletter (see below). Input 
lines beginning with a backslash (\fl) followed by a control character are 
not control lines and are copied to the standard output with the 
backslash removed. Lines beginning with a backslash followed by a 
non-control character are copied in their entirety. 

A keyword is composed of 9 or fewer alphanumerics; the first must be 
alphabetic. A value is any ASCII string that can be created with ed{\)', a 
numeric value is an unsigned string of digits. Keyword values may not con- 
tain blanks or tabs. 

Replacement of keywords by values is done whenever a keyword sur- 
rounded by control characters is encountered on a version control statement. 
The -a keyletter (see below) forces replacement of keywords in all lines of 
text. An uninterpreted control character may be included in a value by 
preceding it with \. If a literal \ is desired, then it too must be preceded by 
\. 

Keyletter Arguments 

-a Forces replacement of keywords surrounded by control characters 
with their assigned value in all text lines and not just in vc state- 
ments. 

-t All characters from the beginning of a line up to and including the 
first tab character are ignored for the purpose of detecting a control 
statement. If one is found, all characters up to and including the 
tab are discarded. 

-cchar Specifies a control character to be used in place of :. 

-s Silences warning messages (not error) that are normally printed on 
the diagnostic output. 

Version Control Statements 

:dcl keyword[, . . ., keyword] 

Used to declare keywords. All keywords must be declared. 
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:asg keyword=value 

Used to assign values to ke5rwords. An asg statement overrides the 
assignment for the corresponding keyword on the vc command line 
and all previous asg's for that keyword. Keywords declared, but not 
assigned values have null values. 

:if condition 



rend 

Used to skip lines of the standard input. If the condition is true, all 
lines between the if statement and the matching end statement are 
copied to the standard output. If the condition is false, all intervening 
lines are discarded, including control statements. Note that interven- 
ing if statements and matching end statements are recognized solely 
for the purpose of maintaining the proper if-end matching. 

The syntax of a condition is: 



<cond> ::= [ "not" ] <or> 

<or> ::= <and> I <and> "I" <or> 

<and> ::= <exp> I <exp> "&" <and> 

<exp> ::= "(" <or> ")" I <value> <op> <value> 

<op> ::= " = " I "!=" I "<" I ">" 

<value> ::= <arbitrary ASCII string> I <numeric string> 



The available operators and their meanings are: 

equal 
not equal 
and 
or 

greater than 
less than 

used for logical groupings 

may only occur immediately after the //, and when 
present, inverts the value of the entire condition 

The > and < operate only on unsigned integer values (e.g., : 012 > 12 
is false). All other operators take strings as arguments (e.g., : 012 != 
12 is true). The precedence of the operators (from highest to lowest) 
is: 

= != > < all of equal precedence 

& 

I 

Parentheses may be used to alter the order of precedence. 

Values must be separated from operators or parentheses by at least 
one blank or tab. 



1=: 

& 

I 

> 
< 



not 
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::text Used for keyword replacement on lines that are copied to the standard 
output. The two leading control characters are removed, and key- 
words surrounded by control characters in text are replaced by their 
value before the line is copied to the output file. This action is 
independent of the -a keyletter. 

:on 

:off Turn on or off keyword replacement on all lines. 
:ctl char 

Change the control character to char. 

:msg message 

Prints the given message on the diagnostic output. 

:err message 

Prints the given message followed by: 

ERROR: err statement on line ... (915) 

on the diagnostic output, vc halts execution and returns an exit code 
of 1. 

SEE ALSO 

ed(l), in the User's/System Administrator's Reference Manual 

EXIT CODES 

- normal 

1 - any error 
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NAME 

what - identify SCCS files 

SYNOPSIS 

what [-s] files 

DESCRIPTION 

The what command searches the given files for all occurrences of the pat- 
tern that get{l) substitutes for %Z% (this is @(#) at this printing) and prints 
out v^hat follov^s until the first >, nev^-line, V or null character. For 
example, if the C program in file f.c contains 

char ident[] = " @(#)identification information " ; 

and f.c is compiled to yield f.o and a.out then the command 
what f.c f.o a.out 

will print 

f.c: identification information 

f.o: identification information 

a.out: identification information 

The what command is intended to be used in conjunction with the com- 
mand get(l), which automatically inserts identifying information, but it can 
also be used where the information is inserted manually. Only one option 
exists: 

-s Quit after finding the first occurrence of pattern in each file. 

SEE ALSO 

get(l). 

DIAGNOSTICS 

Exit status is if any matches are found, otherwise 1. 

BUGS 

It is possible that an unintended occurrence of the pattern @(#) could be 
found just by chance, but this causes no harm in nearly all cases. 
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NAME 

x286emul - emulate XENIX 80286 

SYNOPSIS 

x286emul [arg...] prog286 

DESCRIPTION 

x286emul is an emulator that allows programs from XENIX System V/286 
Release 2.3 or SCO's XENIX System V/286 Release 2.3.2 on the Intel 80286 
to run on the Intel 80386 processor under UNIX System V/386 Release 3.2. 

The UNIX system recognizes an attempt to exec(2) a 286 program, and 
automatically exec's the 286 emulator with the 286 program name as an 
additional argument. It is not necessary to specify the x286emul emulator 
on the command line. The 286 programs can be invoked using the same 
command format as on the XENIX System V/286. 

X286emul reads the 286 program's text and data into memory and maps 
them through the LDT [via $ysi86(2)] as 286 text and data segments. It also 
fills in the jam area, which is used by XENIX programs to do system calls 
and signal returns. X286emul starts the 286 program by jumping to its entry 
point. 

When the 286 program attempts to do a system call, x286emul takes control. 
It does any conversions needed between the 286 system call and the 
equivalent 386 system call, and performs the 386 system call. The results 
are converted to the form the 286 program expects, and the 286 program is 
resumed. 

The following are some of the differences between a program running on a 
286 and a 286 program using x286emul on a 386: 

Attempts to unlink or write on the 286 program v^l fail on the 286 
with ETXTBSY. Under ;c286emM/, they will not fail. 

Ptrace{2) is not supported under x286emul. 

The 286 program must be readable for the emulator to read it. 

FILES 

/bin/x286emul 

The emulator must have this name and be in /bin if it is to be 
automatically invoked when exec{2) is used on a 286 program. 
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NAME 

yacc - yet another compiler-compiler 

SYNOPSIS 

yacc [ -vdlt ] grammar 

DESCRIPTION 

The yacc command converts a context-free grammar into a set of tables for a 
simple automaton v^hich executes an LR(1) parsing algorithm. The grammar 
may be ambiguous; specified precedence rules are used to break ambiguities. 

The output file, y.tab.c, must be compiled by the C compiler to produce a 
program yyparse. This program must be loaded with the lexical analyzer 
program, yylex, as well as main and yyerror, an error-handling routine. 
These routines must be supplied by the user; lex{\) is useful for creating lex- 
ical analyzers usable by yacc. 

If the -V flag is given, the file y.output is prepared, which contains a 
description of the parsing tables and a report on conflicts generated by 
ambiguities in the grammar. 

If the -d flag is used, the file y.tab.h is generated with the #define state- 
ments that associate the yacc-assigned "token codes" with the user-declared 
"tok^n names". This allows source files other than y.tab.c to access the 
token codes. 

If the -1 flag is given, the code produced in y.tab.c will not contain any 
#line constructs. This should only be used after the grammar and the asso- 
ciated actions are fully debugged. 

Runtime debugging code is always generated in y.tab.c under conditional 
compilation control. By default, this code is not included when y.tab.c is 
compiled. However, when y ace's -t option is used, this debugging code 
will be compiled by default. Independent of whether the -t option was 
used, the runtime debugging code is under the control of YYDEBUG, a 
preprocessor s)mibol. If YYDEBUG has a non-zero value, then the debug- 
ging code is included. If its value is zero, then the code will not be 
included. The size and execution time of a program produced without the 
runtime debugging code will be smaller and slightly faster. 

FILES 

y.output 
y.tab.c 

y.tab.h defines for token names 

yacc.tmp, 

yacc.debug, yacc.acts temporary files 
/usr/lib/yaccpar parser prototype for C programs 

SEE ALSO 

lex(l). 

Chapter 6 in the Programmer's Guide. 
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DIAGNOSTICS 

The number of reduce-reduce and shift-reduce conflicts is reported on the 
standard error output; a more detailed report is found in the y.output file. 
Similarly, if some rules are not reachable from the start symbol, this is also 
reported. 

CAVEAT 

Because file names are fixed, at most one yacc process can be active in a 
given directory at a given time. 
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NAME 

intro - introduction to system calls and error numbers 

SYNOPSIS 

#include <errno.h> 

DESCRIPTION 

This section describes all of the system calls. Most of these calls have one 
or more error returns. An error condition is indicated by an otherv^ise 
impossible returned value. This is almost always -1 or the NULL pointer; 
the individual descriptions specify the details. An error number is also 
made available in the external variable ermo. Ermo is not cleared on suc- 
cessful calls, so it should be tested only after an error has been indicated. 

Each system call description attempts to list all possible error numbers. The 
foUov^ing is a complete list of the error numbers and their names as defined 
in <ermo.h>. 

1 EPERM Not ovmer 

Typically this error indicates an attempt to modify a file in some 
v^ay forbidden except to its owner or super-user. It is also returned 
for attempts by ordinary users to do things allowed only to the 
super-user. 

2 ENOENT No such file or directory 

This error occurs when a file name is specified and the file should 
exist but doesn't, or when one of the directories in a path name 
does not exist. 

3 ESRCH No such process 

No process can be found corresponding to that specified by pid in 
kill{2) or ptrace{iy 

4 EINTR Interrupted system call 

An asynchronous signal (such as interrupt or quit), which the user 
has elected to catch, occurred during a system call. If execution is 
resumed after processing the signal, it will appear as if the inter- 
rupted system call returned this error condition. 

5 EIO I/O error 

Some physical I/O error has occurred. This error may in some 
cases occur on a call following the one to which it actually applies. 

6 ENXIO No such device or address 

I/O on a special file refers to a subdevice which does not exist or is 
beyond the limits of the device. It may also occur when, for exam- 
ple, a tape drive is not on-line or no disk pack is loaded on a drive. 

7 E2BIG Arg list too long 

An argument list longer than 5,120 bytes is presented to a member 
of the exec{2) family. 

8 ENOEXEC Exec format error 

A request is made to execute a file which, although it has the 
appropriate permissions, does not start with a valid magic number 
[see fl.0Mf(4)]. 
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9 EBADF Bad file number 

Either a file descriptor refers to no open file, or a re ad (2) [respec- 
tively, write{2)] request is made to a file which is open only for 
writing (respectively, reading). 

10 ECHILD No child processes 

A wait was executed by a process that had no existing or unwaited- 
for child processes. 

1 1 EAG AIN No more processes 

A fork failed because the system's process table is full or the user is 
not allowed to create any more processes. Or a system call failed 
because of insufficient memory or swap space. 

12 ENOMEM Not enough space 

During an exec{2), brk{2\ or sbrk(2), a program asks for more space 
than the system is able to supply. This may not be a temporary 
condition; the maximum space size is a system parameter. The 
error may also occur if the arrangement of text, data, and stack seg- 
ments requires too many segmentation registers, or if there is not 
enough swap space during a fork{2). If this error occurs on a 
resource associated with Remote File Sharing (RFS), it indicates a 
memory depletion wich may be temporary, dependent on system 
activity at the time the call was invoked. 

13 EACCES Permission denied 

An attempt was made to access a file in a way forbidden by the 
protection system. 

14 EFAULT Bad address 

The system encountered a hardware fault in attempting to use an 
argument of a system call. 

15 ENOTBLK Block device required 

A non-block file was mentioned where a block device was required, 
e.g., in mount{2), 

16 EBUSY Device or resource busy 

An attempt was made to mount a device that was already mounted 
or an attempt was made to dismount a device on which there is an 
active file (open file, current directory, mounted-on file, active text 
segment). It will also occur if an attempt is made to enable account- 
ing when it is already enabled. The device or resource is currently 
unavailable. 

17 EEXIST File exists 

An existing file was mentioned in an inappropriate context, e.g., 
link(2). 

18 EXDEV Cross-device link 

A link to a file on another device was attempted. 

19 ENODEV No such device 

An attempt was made to apply an inappropriate system call to a 
device; e.g., read a write-only device. 
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20 ENOTDIR Not a directory 

A non-directory was specified where a directory is required, for 
example in a path prefix or as an argument to chdir{2). 

21 EISDIR Is a directory 

An attempt was made to write on a directory. 

22 EINVAL Invalid argument 

Some invalid argument (e.g., dismounting a non-mounted device; 
mentioning an undefined signal in signal(2) or kill(2); reading or 
writing a file for which lseek(2) has generated a negative pointer). 
Also set by the math functions described in the (3M) entries of this 
manual. 

23 ENFILE File table overflow 

The system file table is full, and temporarily no more opens can be 
accepted. 

24 EMFILE Too many open files 

No process may have more than NOFILES (default 20) descriptors 
open at a time. 

25 ENOTTY Not a character device (or) Not a typewriter 

An attempt was made to ioctl{2) a file that is not a special character 
device. 

26 ETXTBSY Text file busy 

An attempt was made to execute a pure-procedure program that is 
currently open for writing. Also an attempt to open for writing or 
to remove a pure-procedure program that is being executed. 

27 EFBIG File too large 

The size of a file exceeded the maximum file size or ULIMIT [see 
ulimit(2)]. 

28 ENOSPC No space left on device 

During a write(2) to an ordinary file, there is no free space left on 
the device. In fcntl(2), the setting or removing of record locks on a 
file cannot be accomplished because there are no more record 
entries left on the system. 

29 ESPIPE Illegal seek 

An lseek{2) was issued to a pipe. 

30 EROFS Read-only file system 

An attempt to modify a file or directory was made on a device 
mounted read-only. 

31 EMLINK Too many links 

An attempt to make more than the maximum number of links 
(1000) to a file. 

32 EPIPE Broken pipe 

A write on a pipe for which there is no process to read the data. 
This condition normally generates a signal; the error is returned if 
the signal is ignored. 
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33 EDOM Math argument 

The argument of a function in the math package (3M) is out of the 
domain of the function. 

34 ERANGE Result too large 

The value of a function in the math package (3M) is not represent- 
able v^thin machine precision. 

35 ENOMSG No message of desired type 

An attempt was made to receive a message of a type that does not 
exist on the specified message queue [see msgop{2)]. 

36 EIDRM Identifier removed 

This error is returned to processes that resume execution due to the 
removal of an identifier from the file system's name space [see 
msgctl{2\ semctl{l\ and shmctl{l)]. 

37 ECHRNG Channel number out of range 

38 EL2NSYNC Level 2 not synchronized 

39 EL3HLT Level 3 halted 

40 EL3RST Level 3 reset 

41 ELNRNG Link number out of range 

42 EUNATCH Protocol driver not attached 

43 ENOCSI No CSI structure available 

44 EL2HLT Level 2 halted 

45 EDEADLK Deadlock 

A deadlock situation was detected and avoided. This error pertains 
to file and record locking. 

46 ENOLCK No lock 

In fcntl(2) the setting or removing of record locks on a file cannot be 
accomplished because there are no more record entries left on the 
system. 

50 EBADE Invalid exchange 

51 EBADR Invalid request descriptor 

52 EXFULL Exchange full 
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53 ENOANO No anode 

54 EBADRQC Invalid request node 

55 EBADSLT Invalid slot 

56 EDEADLOCK File locking deadlock error 

57 EBFONT Bad font file fmt 

60 ENOSTR Not a stream 

A putmsg(2) or getmsg(2) system call was attempted on a file 
descriptor that is not a STREAMS device. 

61 ENODATA No data (for no delay I/O) 

62 ETIME Stream ioctl timeout 

The timer set for a STREAMS ioctl(2) call has expired. The cause of 
this error is device specific and could indicate either a hardware or 
software failure, or perhaps a timeout value that is too short for the 
specific operation. The status of the ioctl{2) operation is indeter- 
minate. 

63 ENOSR No stream resources 

During a STREAMS open(2), either no STREAMS queues or no 
STREAMS head data structures were available. 

64 ENONET Machine is not on the network 

This error is Remote File Sharing (RFS)-specific. It occurs when 
users try to advertise, unadvertise, mount, or unmount remote 
resources while the machine has not done the proper start-up to 
connect to the network. 

65 ENOPKG No package 

This error occurs when users attempt to use a system call from a 
package which has not been installed. 

66 EREMOTE Resource is remote 

This error is RFS-specific. It occurs when users try to advertise a 
resource which is not on the local machine, or try to 
mount/unmount a device (or path name) that is on a remote 
machine. 

67 ENOLINK Virtual circuit is gone 

This error is RFS-specific. It occurs when the link (virtual circuit) 
connecting to a remote machine is gone. 

68 EADV Advertise error 

This error is RFS-specific. It occurs when users try to advertise a 
resource which has been advertised already, or try to stop the RFS 
while there are resources still advertised, or try to force unmount a 
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resource when it is still advertised. 

69 ESRMNT Srmount error 

This error is RFS-specific. It occurs when users try to stop RFS while 
there are resources still mounted by remote machines. 

70 ECOMM Communication error 

This error is RFS-specific. It occurs when trying to send messages to 
remote machines but no virtual circuit can be found. 

71 EPROTO Protocol error 

Some protocol error occurred. This error is device-specific, but is 
generally not related to a hardware failure. 

74 EMULTIHOP Multihop attempted 

This error is RFS-specific. It occurs when users try to access remote 
resources which are not directly accessible. 

76 EDOTDOT Cross mount point 

77 EBADMSG Bad message 

During a read{2), getmsg(2), or ioctl{2) I_RECVFD system call to a 
STREAMS device, something has come to the head of the queue that 
can't be processed. That something depends on the system call: 

read{l) — control information or a passed file descriptor. 

getmsg{2) — passed file descriptor. 

ioctl(2) — control or data information. 

80 ENOTUNIQ Given log name not unique 

81 EBADFD f.d. invalid for this operation 

82 EREMCHG Remote address changed 

83 ELIBACC Cannot access a needed shared library 

Trying to exec(2) an a.out that requires a shared library (to be linked 
in) and the shared library doesn't exist or the user doesn't have per- 
mission to use it. 

84 ELIBBAD Accessing a corrupted shared library 

Trying to exec{2) an a.out that requires a shared library (to be linked 
in) and exec(2) could not load the shared library. The shared library 
is probably corrupted. 

85 ELIBSCN .lib section in a.out corrupted 

Trying to exec(2) an a.out that requires a shared library (to be linked 
in) and there was erroneous data in the .lib section of the a.out. The 
.lib section tells exec{2) what shared libraries are needed. The a.out 
is probably corrupted. 

86 ELIBMAX Attempting to link in more shared libraries than system limit 

Trying to exec(2) an a.out that requires more shared libraries (to be 
linked in) than is allowed on the current configuration of the sys- 
tem. See the Operations /System Administration Guide. 
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87 ELIBEXEC Cannot exec a shared library directly 

Trying to exec{2) a shared library directly. This is not allowed. 

88-134 Reserved numbers 

135 EUCLEAN Structure needs cleaning 

An attempt was made to Tnount(lM) a file system whose file super- 
block is not flagged clean. 

137 ENOTNAM Not a name file 

An attempt to open a semaphore was issued using an invalid XENIX 
semaphore identifier. Or, a process attempted to attach or detach a 
shared data segment on a file that exists but is not a shared data 
type. 

138 ENAVAIL Not available 

An attempt was made to use a XENIX semaphore that has not been 
initialized, 

139 EISNAM Is a name file 

A XENIX name file (semaphore, shared data, etc.) was specified 
when not expected. 

140 EREMOTEIO Remote I/O error 
DEnNITIONS 

Process ID. Each active process in the system is uniquely identified by a 
positive integer called a process ID. The range of this ID is from 1 to 
30,000. By convention, process-ID and 1 are reserved for special system 
processes. 

Parent Process ID. A new process is created by a currently active process 
[see fork(2)]. The parent process ID of a process is the process ID of its crea- 
tor. 

Process Group ID. Each active process is a member of a process group that 
is identified by a positive integer called the process group ID. This ID is the 
process ID of the group leader. This grouping permits the signaling of 
related processes [see kill{2)]. 

Process Group Leader. A process group leader is any process whose pro- 
cess group ID is the same as its process ID. Any process that is not a pro- 
cess group leader may detach itself from its current process group and 
become a new process group leader by calling the setpgrp{2). 

Tty Group ID. Each active process can be a member of a terminal group 
that is identified by a positive integer called the tty group ID. This grouping 
is used to terminate a group of related processes upon termination of one of 
the processes in the group [see exit(2) and signal{2)]. 
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Real User ID and Real Group ID. Each user allowed on the system is iden- 
tified by a positive integer (0 to 65535) called a real user ID. 

Each user is also a member of a group. The group is identified by a positive 
integer called the real group ID. 

An active process has a real user ID and real group ID that are set to the real 
user ID and real group ID, respectively, of the user responsible for the crea- 
tion of the process. 

Effective User ID and Effective Group ID. An active process has an effec- 
tive user ID and an effective group ID that are used to determine file access 
permissions (see below). The effective user ID and effective group ID are 
equal to the process's real user ID and real group ID respectively, unless the 
process or one of its ancestors evolved from a file that had the set-user-ID 
bit or set-group ID bit set [see exec{2)]. 

Super-user. A process is recognized as a super-user process and is granted 
special privileges, such as immunity from file permissions, if its effective 
user ID is 0. 

Special Processes. The processes with a process ID of and a process ID of 
1 are special processes and are referred to as procO and prod. 

ProcO is the scheduler. Prod is the initialization process (init). Procl is the 
ancestor of every other process in the system and is used to control the pro- 
cess structure. 

File Descriptor. A file descriptor is a small integer used to do I/O on a file. 
The value of a file descriptor is from to (NOFILES - 1). A process may 
have no more than NOFILES file descriptors open simultaneously. A file 
descriptor is returned by system calls such as open(2) or pipe(l). The file 
descriptor is used as an argument by calls such as read{l), write{l), ioctl{2), 
and close(l). 

File Name. Names consisting of 1 to 14 characters may be used to name 
an ordinary file, special file or directory. 

These characters may be selected from the set of all character values exclud- 
ing \0 (null) and the ASCII code for / (slash). 

Note that it is generally unwise to use *, ?, [, or ] as part of file names 
because of the special meaning attached to these characters by the shell [see 
s^(l)]. Other characters to avoid are the hypen, blank, tab, <, >, 
blackslash, single and double quotes, accent grave, vertical bar, caret, curly 
braces, and parentheses. Although permitted, the use of unprintable charac- 
ters in file names should be avoided. 

Path Name and Path Prefix. A path name is a null-terminated character 
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string starting with an optional slash (/), followed by zero or more directory 
names separated by slashes, optionally followed by a file name. 

If a path name begins with a slash, the path search begins at the root direc- 
tory. Otherwise, the search begins from the current working directory. 

A slash by itself names the root directory. An attempt to create or delete 
the path-name slash by itself is undefined and may be considered an error. 
The meaning of . and .. are defined under directory. 

Unless specifically stated otherwise, the null path name is treated as if it 
named a nonexistent file. 

Directory. Directories organize files into a hierarchical system of files 
where directories are the nodes in the hierarchy. A directory is a file that 
catalogues the list of files, including directories (sub-directories), that are 
directly beneath it in the hierarchy. Directory entries are called links. By 
convention, a directory contains at least two links, . and .., referred to as dot 
and dot-dot respectively. Dot refers to the directory itself and dot-dot refers 
to its parent directory. The root-directory, which is the top-most node of 
the hierarchy, has itself as its parent-directory. The path-name of the root- 
directory is / and the parent directory of the root-directory is /. 

Root Directory and Current Working Directory. Each process has associ- 
ated with it a concept of a root directory and a current working directory for 
the purpose of resolving path name searches. The root directory of a pro- 
cess need not be the root directory of the root file system. 

File Access Permissions. Read, write, and execute/search permissions on a 
file are granted to a process if one or more of the following is true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches the user ID of the 
owner of the file; and the appropriate access bit of the "owner" por- 
tion (0700) of the file mode is set. 

The effective user ID of the process does not match the user ID of 
the owner of the file; and the effective group ID of the process 
matches the group of the file; and the appropriate access bit of the 
"group" portion (0070) of the file mode is set. 

The effective user ID of the process does not match the user ID of 
the owner of the file; and the effective group ID of the process does 
not match the group ID of the file; and the appropriate access bit of 
the "other" portion (0007) of the file mode is set. 

Otherwise, the corresponding permissions are denied. 

Message Queue Identifier. A message queue identifier (msqid) is a unique 
positive integer created by a msgget{2) system call. Each msqid has a mes- 
sage queue and a data structure associated with it. The data structure is 
referred to as msqid— ds and contains the following members: 
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struct 


ipc_perm msg_perm; 


struct 


msg *msg_first; 


struct 


msg *msg_last; 


ushort 


msg_cbytes; 


ushort 


msg__qnum; 


ushort 


msg_qbytes; 


ushort 


msg_lspid; 


ushort 


msg_Jrpid; 


time_t 


msg—stime; 


time_t 


msg__rtime; 


time_t 


msg_ctime; 



ushort 


cuid; 


ushort 


cgid; 


ushort 


uid; 


ushort 


gid; 


ushort 


mode; 


ushort 


seq; 


key_t 


key; 



msg_perm is an ipc_perm structure that specifies the message operation 
permission (see below). This structure includes the following members: 

/* creator user id */ 
/* creator group id */ 
/* user id */ 
/* group id */ 
/* r/w permission */ 
/* slot usage sequence # */ 
/* key */ 

msg *msg_first 

is a pointer to the first message on the queue, 
msg *msg-Jast 

is a pointer to the last message on the queue. 

msg_cbytes 

is the current number of bytes on the queue. 
msg_qnum 

is the number of messages currently on the queue, 
msg^qbytes 

is the maximum number of bytes allowed on the queue, 
msg— Ispid 

is the process id of the last process that performed a msgsnd opera- 
tion. 

msg_lrpid 

is the process id of the last process that performed a msgrcv opera- 
tion. 

msg-stime 

is the time of the last msgsnd operation. 

msg— rtime 

is the time of the last msgrcv operation. 

msg—ctime 

is the time of the last msgctl(l) operation that changed a member of 
the above structure. 
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Message Operation Permissions. In the msgop{2) and msgctl(2) system call 
descriptions, the permission required for an operation is given as 
"{token}", where "token" is the type of permission needed, interpreted as 
follows: 



00400 Read by user 

00200 Write by user 

00040 Read by group 

00020 Write by group 

00004 Read by others 

00002 Write by others 



Read and write permissions on a msqid are granted to a process if one or 
more of the following is true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches msg— perm.cuid or 
msg—perm.uid in the data structure associated with msqid and the 
appropriate bit of the "user" portion (0600) of msg_perm.mode is 
set. 

The effective group ID of the process matches msg_-perm.cgid or 
msg_-perm.gid and the appropriate bit of the "group" portion (060) 
of msg— perm.mode is set. 

The appropriate bit of the "other" portion (006) of 
msg_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 



Semaphore Identifier. A semaphore identifier (semid) is a unique positive 
integer created by a semget{2) system call. Each semid has a set of sema- 
phores and a data structure associated with it. The data structure is referred 
to as semid^ds and contains the following members: 

struct ipc_perm sem_perm; /* operation permission struct */ 



struct sem *sem__base; 

ushort sem_nsems; 

time^t sem_otime; 

time_t sem_ctime; 



/* ptr to first semaphore in set */ 
/* number of sems in set */ 
/* last operation time */ 
/* last change time */ 
/* Times measured in sees since */ 
/* 00:00:00 GMT, Jan. 1, 1970 */ 



sem—perm is an ipc_perm structure that specifies the semaphore operation 
permission (see below). This structure includes the following members: 

/* user id */ 
/* group id */ 
/* creator user id */ 
/* creator group id */ 
/* r/a permission */ 
/* slot usage sequence number */ 



ushort 


uid; 


ushort 


gid; 


ushort 


cuid; 


ushort 


cgid; 


ushort 


mode; 


ushort 


seq; 
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key_t key; /* key */ 

sem_nsems 

is equal to the number of semaphores in the set. Each semaphore 
in the set is referenced by a positive integer referred to as a 
sem—uum . Sem__num values run sequentially from to the value of 
sem_nsems minus 1. 

sein-_otime 

is the time of the last semop(2) operation. 

sem-.ctime 

is the time of the last semctl{2) operation that changed a member of 
the above structure. 

A semaphore is a data structure called sent that contains the following 
members: 

ushort semval; /* semaphore value */ 
short sempid; /* pid of last operation */ 
ushort semncnt; /* # awaiting semval > cval */ 
ushort semzcnt; /* # awaiting semval = */ 

semval 

is a non-negative integer which is the actual value of the sema- 
phore. 

sempid 

is equal to the process ID of the last process that performed a sema- 
phore operation on this semaphore. 

semncnt 

is a count of the number of processes that are currently suspended 
awaiting this semaphore's semval to become greater than its current 
value. 

semzcnt 

is a count of the number of processes that are currently suspended 
awaiting this semaphore's semval to become zero. 

Semaphore Operation Permissions. In the semopil) and semctl{l) system 
call descriptions, the permission required for an operation is given as 
"{token}", where "token" is the type of permission needed, interpreted as 
follows: 

00400 Read by user 

00200 Alter by user 

00040 Read by group 

00020 Alter by group 

00004 Read by others 

00002 Alter by others 

Read and alter permissions on a semid are granted to a process if one or 
more of the following is true: 
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The effective user ID of the process is super-user. 

The effective user ID of the process matches sem_perm.cuid or 
seiiL-.perm.uid ii\ the data structure associated v^th semid, and the 
appropriate bit of the "user" portion (0600) of 8em_perm.mode is 
set. 

The effective group ID of the process matches sem_perm.cgid or 
seixiL.penn.gid and the appropriate bit of the "group" portion (060) 
of sem_perm.mode is set. 

The appropriate bit of the "other" portion (006) of sem— perm.mode 
is set. 

Otherwise, the corresponding permissions are denied. 



Shared Memory Identifier. A shared memory identifier {shmid) is a unique 
positive integer created by a shmget{2) system call. Each shmid has a seg- 
ment of memory (referred to as a shared memory segment) and a data struc- 
ture associated with it. (Note that these shared memory segments must be 
explicitly removed by the user after the last reference to them is removed.) 
The data structure is referred to as shmid— ds and contains the following 
members: 



ipc_perm shm_perm; /* operation permission struct */ 
size of segment */ 
ptr to region structure */ 
for swap compatibility */ 
pid of last operation */ 
creator pid */ 

number of current attaches */ 
used only for shminfo */ 
last attach time */ 
last detach time */ 
last change time */ 
Times measured in sees since */ 
00:00:00 GMT, Jan. 1, 1970 */ 



struct 

int shm_-segsz; 

struct region *shm_reg; 

char pad[4]; 

ushort shm_lpid; 

ushort shm— .cpid; 

ushort shm__nattch; 

ushort shm_cnattch; 

time_t shm_atime; 

time—t shm—dtime; 

time—t shm_ctime; 



I* 

/* I 

/*] 
/*, 

/•I 
/* 1 

/*] 
/*i 

/*: 

/*' 
/», 



shm— perm is an ipc_perm structure that specifies the shared memory 
operation permission (see below). This structure includes the following 
members: 



/* creator user id */ 

/* creator group id */ 

/* user id */ 

/* group id */ 

/* r/w permission */ 

/* slot usage sequence # */ 

/* key */ 



ushort cuid; 

ushort cgid; 

ushort uid; 

ushort gid; 

ushort mode; 

ushort seq; 

key—t key; 

shnu-segsz 

specifies the size of the shared memory segment in bytes. 
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shm_cpid 

is the process id of the process that created the shared memory 
identifier. 

shnLJpid 

is the process id of the last process that performed a shmop{2) 
operation. 

shm-jtiattch 

is the number of processes that currently have this segment 
attached. 

shm^atime 

is the time of the last shmat{2) operation, 

shm__dtime 

is the time of the last shmdt(2) operation. 

shm_ctime 

is the time of the last shmctl{2) operation that changed one of the 
members of the above structure. 

Shared Memory Operation Permissions. In the shmop{2) and shmctl{2) 
system call descriptions, the permission required for an operation is given as 
"{token}", v^here "token" is the type of permission needed, interpreted as 
follov^s: 



00400 Read by user 

00200 Write by user 

00040 Read by group 

00020 Write by group 

00004 Read by others 

00002 Write by others 



Read and v^rite permissions on a shmid are granted to a process if one or 
more of the following is true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches shm-_perm.cuid or 
shm_perm.uid in the data structure associated v^ith shmid and the 
appropriate bit of the "user" portion (0600) of shm_perm.mode is 
set. 

The effective group ID of the process matches shm_perm.cgid or 
shm—perm.gid and the appropriate bit of the "group" portion (060) 
of shm_perm.mode is set. 

The appropriate bit of the "other" portion (06) of shm. perm.mode 
is set. 

Othenvise, the corresponding permissions are denied. 

STREAMS. A set of kernel mechanisms that support the development of 
network services and data communication drivers. It defines interface 
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standards for character input/output within the kernel and between the ker- 
nel and user-level processes. The STREAMS mechanism is composed of util- 
ity routines, kernel facilities, and a set of data structures. 

Stream. A stream is a full-duplex data path within the kernel between a 
user process and driver routines. The primary components are a stream 
head, a driver, and zero or more modules between the stream head and 
driver. A stream is analogous to a shell pipeline except that data flow and 
processing are bidirectional. 

Stream Head. In a stream, the stream head is the end of the stream that pro- 
vides the interface between the stream and a user process. The principal 
functions of the stream head are processing STREAMS-related system calls 
and passing data and information between a user process and the stream. 

Driver. In a stream, the driver provides the interface between peripheral 
hardware and the stream. A driver can also be a pseudo-driver, such as a 
multiplexer or log driver [see log{7)], which is not associated with a hardware 
device. 

Module. A module is an entity containing processing routines for input 
and output data. It always exists in the middle of a stream, between the 
stream's head and a driver. A module is the STREAMS counterpart to the 
commands in a shell pipeline except that a module contains a pair of func- 
tions which allow independent bidirectional {downstream and upstream) data 
flow and processing. 

Downstream. In a stream, the direction from stream head to driver. 

Upstream. In a stream, the direction from driver to stream head. 

Message. In a stream, one or more blocks of data or information, with asso- 
ciated STREAMS control structures. Messages can be of several defined 
types, which identify the message contents. Messages are the only means of 
transferring data and communicating within a stream. 

Message Queue. In a stream, a linked list of messages awaiting processing 
by a module or driver. 

Read Queue. In a stream, the message queue in a module or driver contain- 
ing messages moving upstream. 

Write Queue. In a stream, the message queue in a module or driver contain- 
ing messages moving downstream. 
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Multiplexer. A multiplexer is a driver that allov^s streams associated with 
several user processes to be connected to a single driver, or several drivers 
to be connected to a single user process. STREAMS does not provide a gen- 
eral multiplexing driver, but does provide the facilities for constructing them 
and for connecting multiplexed configurations of streams, 
SEE ALSO 

intro(3). 
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NAME 

access - determine accessibility of a file 

SYNOPSIS 

#include <unistd.h> 



int access (path, amode) 
char *path; 
int amode; 

DESCRIPTION 

The path argument points to a path name naming a file. The access func- 
tion checks the named file for accessibility according to the bit pattern con- 
tained in amode, using the real user ID in place of the effective user ID and 
the real group ID in place of the effective group ID. The bit pattern con- 
tained in amode is constructed as follows: 

04 read 

02 write 

01 execute (search) 

00 check existence of file 



The symbolic constants for the argument amode are defined by the 
<unistd.h> header file and are as follows: 

Name Description 

R— OK test for read permission. 

W— OK test for write permission. 

X_OK test for execute (search) permission. 

F_OK test for existence of file. 



The argument amode is either the logical OR of one or more of the values 
of the symbolic constants for R_OK, W_OK, and X_OK or is the value of 
the symbolic constant F_OK. 

Access to the file is denied if one or more of the following is true: 

[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENT] Read, write, or execute (search) permission is 

requested for a null path name. 
[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the 

path prefix. 

[EROFS] Write access is requested for a file on a read-only 

file system. 

[ETXTBSY] Write access is requested for a pure procedure 

(shared text) file that is being executed. 
[EACCES] Permission bits of the file mode do not permit 

the requested access. 
[EFAULT] Path points outside the allocated address 

space for the process. 
[EINTR] A signal was caught during the access 

system call. 

[ENOLINK] Path points to a remote machine and the link 
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to that machine is no longer active. 
[EMULTIHOP] Components of path require hopping to multiple 
remote machines. 

The owner of a file has permission checked with respect to the "owner" 
read, write, and execute mode bits. Members of the file's group other than 
the owner have permissions checked with respect to the "group" mode bits, 
and all others have permissions checked with respect to the "other" mode 
bits. 

SEE ALSO 

chmod(2), stat(2). 

DIAGNOSTICS 

If the requested access is permitted, a value of is returned. Otherwise, a 
value of -1 is returned and ermo is set to indicate the error. 
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NAME 

acct - enable or disable process accounting 

SYNOPSIS 

int acct (path) 
char *path; 

DESCRIPTION 

acct is used to enable or disable the system process accounting routine. If 
the routine is enabled, an accounting record will be written on an account- 
ing file for each process that terminates. Termination can be caused by one 
of two things: an exit call or a signal [see exit{2) and signal{2)]. The effec- 
tive user ID of the calling process must be super-user to use this call. 

path points to a pathname naming the accounting file. The accounting file 
format is given in acct (4^). 

The accounting routine is enabled if path is non-zero and no errors occur 
during the system call. It is disabled if path is zero and no errors occur dur- 
ing the system call. 

acct will fail if one or more of the following is true: 

[EPERM] The effective user of the calling process is not super-user. 

[EBUSY] An attempt is being made to enable accounting when it is 

already enabled. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] One or more components of the accounting file path name 

do not exist. 

[EACCES] The file named by path is not an ordinary file. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] Path points to an illegal address. 

SEE ALSO 

exit(2), signal(2), acct(4). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

alarm - set a process alarm clock 

SYNOPSIS 

unsigned alarm (sec) 
unsigned sec; 

DESCRIPTION 

The alarm system call instructs the alarm clock of the calling process to send 
the signal SIGALRM to the calling process after the number of real time 
seconds specified by sec have elapsed [see signal{2)]. 

Alarm requests are not stacked; successive calls reset the alarm clock of the 
calling process. 

If sec is 0, any previously made alarm request is canceled. The fork(2) sys- 
tem call sets the alarm clock of a new process to 0. A process created by 
the exec(2) family of calls inherits the time left on the old process's alarm 
clock. 

SEE ALSO 

exec(2), fork(2), pause(2), signal(2), sigpause(2), sigset(2). 
DIAGNOSTICS 

The alarm system call returns the amount of time previously remaining in 
the alarm clock of the calling process. 
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NAME 

brk, sbrk - change data segment space allocation 

SYNOPSIS 

int brk (endds) 
char *endds; 

char *sbrk (incr) 
int incr; 

DESCRIPTION 

The brk and sbrk system calls are used to change dynamically the amount of 
space allocated for the calling process's data segment [see exec{2)]. The 
change is made by resetting the process's break value and allocating the 
appropriate amount of space. The break value is the address of the first 
location beyond the end of the data segment. The amount of allocated 
space increases as the break value increases. Nev^ly allocated space is set to 
zero. If, hov^ever, the same memory space is reallocated to the same pro- 
cess, its contents are undefined. 

The brk system call sets the break value to endds and changes the allocated 
space accordingly. 

The sbrk system call adds incr bytes to the break value and changes the 
allocated space accordingly. Incr can be negative, in which case the amount 
of allocated space is decreased. 

The brk and sbrk system calls will fail without making any change in the 
allocated space if one or more of the following is true: 



RETURN VALUE 

Upon successful completion brk returns a value of 0, and sbrk returns the 
old break value. Otherwise, a value of -1 is returned and errno is set to 
indicate the error. 

SEE ALSO 

exec(2), shmop(2), ulimit(2), end(3C). 



[ENOMEM] 



Such a change would result in more space being allo- 
cated than is allowed by the system-imposed max- 
imum process size [see ulimit{2)]. 



[EAGAIN] 



Total amount of system memory available for a read 
during physical ID is temporarily insufficient [see 
shmop{2)]. This may occur even though the space 
requested was less than the system-imposed max- 
imum process size [see ulimit{2)]. 
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NAME 

chdir - change working directory 

SYNOPSIS 

int chdir (path) 
char *path; 

DESCRIPTION 

Path points to the path name of a directory, chdir causes the named direc- 
tory to become the current working directory, the starting point for path 
searches for path names not beginning with /. 

chdir will fail and the current working directory will be unchanged if one or 
more of the following is true: 



[ENOTDIR] 
[ENOENT] 
[EACCES] 

[EFAULT] 

[EINTR] 
[ENOLINK] 

[EMULTIHOP] 



A component of the path name is not a directory. 
The named directory does not exist. 

Search permission is denied for any component of the path 



name. 



Path points outside the allocated address space of the pro- 
cess. 

A signal was caught during the chdir system call. 

Path points to a remote machine and the link to that 
machine is no longer active. 

Components of path require hopping to multiple remote 
machines. 



SEE ALSO 

chroot(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and ermo is set to indicate the error. 
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NAME 

chmod - change mode of file 

SYNOPSIS 

int chmod (path, mode) 
char *path; 
int mode; 

DESCRIPTION 

The Path argument points to a path name naming a file. The chmod system 
call sets the access permission portion of the named file's mode according to 
the bit pattern contained in mode. 

Access permission bits are interpreted as follows: 

04000 Set user ID on execution. 

020#0 Set group ID on execution if # is 7, 5, 3, or 1 

Enable mandatory file/record locking if # is 6, 4, 2, or 

01000 Save text image after execution. 

00400 Read by owner. 

00200 Write by owner. 

00100 Execute (search if a directory) by owner. 

00070 Read, write, execute (search) by group. 

00007 Read, write, execute (search) by others. 

The effective user ID of the process must match the owner of the file or be 
super-user to change the mode of a file. 

If the effective user ID of the process is not super-user and the file is not a 
directory, mode bit 01000 (save text image on execution) is cleared. 

If the effective user ID of the process is not super-user and the effective 
group ID of the process does not match the group ID of the file, mode 
bit 02000 (set group ID on execution) is cleared. 

If a 410 executable file has the sticky bit (mode bit 01000) set, the operating 
system will not delete the program text from the swap area when the last 
user process terminates. If a 413 executable file has the sticky bit set, the 
operating system will not delete the program text from memory when the 
last user process terminates. In either case, if the sticky bit is set, the text 
will already be available (either in a swap area or in memory) when the 
next user of the file executes it, thus making execution faster. 

Overall, if a directory is writable and has the sticky bit set, files within that 
directory can only be removed if one or more of the following is true [see 
unlink(2)]: 

the user owns the file 
the user owns the directory 
the file is writable to the user 
the user is the super-user 
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If the mode bit 02000 (set group ID on execution) is set and the mode bit 
00010 (execute or search by group) is not set, mandatory file/record locking 
will exist on a regular file. This may effect future calls to open(2), creat{2), 
read{l), and write{2) on this file. 

chmod will fail and the file mode will be unchanged if one or more of the 
following is true: 

[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the path 

prefix. 

[EPERM] The effective user ID does not match the owner of the file 

and the effective user ID is not super-user. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] Path points outside the allocated address space of the pro- 

cess. 

[EINTR] A signal was caught during the chmod system call. 

[ENOLINK] Path points to a remote machine and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

chown(2), creat(2), fcntl(2), mknod(2), open(2), read(2), write(2). 
chmod(l) in the User's/System Administrator's Reference Manual 
DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and ermo is set to indicate the error. 
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NAME 

chown - change owner and group of a file 

SYNOPSIS 

int chown (path, owner, group) 

char «path; 

int owner, group; 

DESCRIPTION 

Path points to a path name naming a file. The owner ID and group ID of 
the named file are set to the numeric values contained in owner and group 
respectively. 

Only processes with effective user ID equal to the file owner or super-user 
may change the ownership of a file. 

If chown is invoked by other than the super-user, the set-user-ID and set- 
group-ID bits of the file mode, 04000 and 02000 respectively, will be 
cleared. 

chown will fail and the owner and group of the named file will remain 
unchanged if one or more of the following is true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the path 

prefix. 

[EPERM] The effective user ID does not match the owner of the file 

and the effective user ID is not super-user. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] Path points outside the allocated address space of the pro- 

cess. 

[EINTR] A signal was caught during the chown system call. 

[ENOLINK] Path points to a remote machine and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

chmod(2). 

chown(l) in the User's/System Administrator's Reference Manual. 
DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

chroot - change root directory 

SYNOPSIS 

int chroot (path) 
char *path; 

DESCRIPTION 

The path argument points to a path name naming a directory. The chroot 
system call causes the named directory to become the root directory, the 
starting point for path searches for path names beginning with /. The 
user's working directory is unaffected by the chroot system call. 

The effective user ID of the process must be super-user to change the root 
directory. 

The .. entry in the root directory is interpreted to mean the root directory 
itself. Thus, .. cannot be used to access files outside the subtree rooted at 
the root directory. 

The chroot system call will fail and the root directory will remain 
unchanged if one or more of the following is true: 

[ENOTDIR] Any component of the path name is not a directory. 

[ENOENT] The named directory does not exist. 

[EPERM] The effective user ID is not super-user. 

[EFAULT] The path argument points outside the allocated address 

space of the process. 

[EINTR] A signal was caught during the chroot system call. 

[ENOLINK] The Path argument points to a remote machine and the link 
to that machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

chdir(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and ermo is set to indicate the error. 
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NAME 

close - close a file descriptor 

SYNOPSIS 

int close (tildes) 
int tildes; 

DESCRIPTION 

The fildes argument is a file descriptor obtaii\ed from a creat, open, dup, 
fcntl, or pipe system call. The close system call closes the file descriptor 
indicated by fildes. All outstanding record locks owned by the process (on 
the file indicated by fildes) are removed. 

If a STREAMS [see intro{l)] file is closed, and the calling process had previ- 
ously registered to receive a SIGPOLL signal [see signaUl) and sigset{l)\ for 
events associated with that file [see I_SETSIG in streamio{7)], the calling pro- 
cess vdll be unregistered for events associated with the file. The last close 
for a stream causes the stream associated with fildes to be dismantled. If 
O— NDELAY is not set and there have been no signals posted for the stream, 
close waits up to 15 seconds, for each module and driver, for any output to 
drain before dismantling the stream. If the 0_NDELAY flag is set or if there 
are any pending signals, close does not wait for output to drain and disman- 
tles the stream immediately. 

The named file is closed unless one or more of the following is true: 

[EBADF] The fildes argument is not a valid open file descriptor. 

[EINTR] A signal was caught during the close system call. 

[ENOLINK] Fildes is on a remote machine and the link to that machine 
is no longer active. 

SEE ALSO 

creat(2), dup(2), exec(2), fcntl(2), intro(2), open(2), pipe(2), signal(2), sig- 
set(2). 

streamio(7) in the User's /System Administrator's Reference Manual. 
DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and ermo is set to indicate the error. 
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NAME 

creat - create a new file or rewrite an existing one 

SYNOPSIS 

#include <8ys/types.h> 
#include <sys/stat.h> 

int creat (path, mode) 
char *psdh; 
int mode; 

DESCRIPTION 

The creat system call creates a new ordinary file or prepares to rewrite an 
existing file named by the path name pointed to by path. 

If the file exists, the length is truncated to and the mode and owner are 
unchanged. Otherwise, the file's owner ID is set to the effective user ID of 
the process; the group ID of the process is set to the effective group ID of 
the process; and the low-order 12 bits of the file mode are set to the value 
of mode modified as follows: 

All bits set in the process's file mode creation mask are cleared [see 
umask{2)]. 

The "save text image after execution bit" of the mode is cleared [see 
chmod(2)]. 

Upon successful completion, a write-only file descriptor is returned and the 
file is open for writing, even if the mode does not permit writing. The file 
pointer is set to the beginning of the file. The file descriptor is set to remain 
open across exec system calls [see fcntl{2)]. No process may have more 
than 20 files open simultaneously. A new file may be created with a mode 
that forbids writing. 

Symbolic constants defining the access permission bits are specified in the 
<sys/stat.h> header file and should be used to construct mode [see 
chmod(2)]. 

The call creat(path, mode) is equivalent to the following [see open(2)]: 

open (path, 0_WR0NLY | 0__CREAT | 0__TRUNC , mode) 

The creat system call fails if one or more of the following is true: 
[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENT] A component of the path prefix does not exist. 



[EACCES] 



Search permission is denied on a component of the path 
prefix. 



[ENOENT] 
[EACCES] 



The path name is null. 



The file does not exist and the directory in which the file is 
to be created does not permit writing. 



[EROFS] 



The named file resides or would reside on a read-only file 
system. 
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[ETXTBSY] The file is a pure procedure (shared text) file that is being 

executed. 

[EACCES] The file exists and write permission is denied. 

[EISDIR] The named file is an existing directory. 

[EMFILE] NOFILES file descriptors are currently open. 

[EFAULT] The path argument points outside the allocated address 

space of the process. 

[ENFILE] The system file table is full. 

[E AGAIN] The file exists, mandatory file/record locking is set, and 

there are outstanding record locks on the file [see chmod{2)], 

[EINTR] A signal was caught during the creat system call. 

[ENOLINK] Path points to a remote machine and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

[ENOSPC] The file system is out of inodes. 

SEE ALSO 

chmod(2), close(2), dup(2), fcntl(2), lseek(2), open(2), read{2), umask(2), 
write(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely the file descrip- 
tor, is returned. Otherwise, a value of -1 is returned, and ermo is set to 
indicate the error. 
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NAME 

dup - duplicate an open file descriptor 

SYNOPSIS 

int dup (tildes) 
int tildes; 

DESCRIPTION 

The fildes argument is a file descriptor obtained from a creat, open, dup, 
fcntl, or pipe system call. The dup system call returns a new file descriptor 
having the following in common with the original: 

Same open file (or pipe) 

Same file pointer (i.e., both file descriptors share one file pointer) 

Same access mode (read, write, or read/ write) 

The new file descriptor is set to remain open across exec system calls [see 
fcntl{2)]. 

The file descriptor returned is the lowest one available. 

The dup system call will fail if one or more of the following is true: 

[EBADF] The fildes argument is not a valid open file descriptor. 

[EINTR] A signal was caught during the dup system call. 

[EMFILE] NOFILES file descriptors are currently open. 

[ENOLINK] Fildes is on a remote machine and the link to tjKat machine 
is no longer active. 

SEE ALSO 

close(2), creat(2), exec(2), fcntl(2), open(2), pipe(2), lockf(3C). 
DIAGNOSTICS 

Upon successful completion a non-negative integer, namely the file descrip- 
tor, is returned. Otherwise, a value of -1 is rehimed, and ermo is set to 
indicate the error. 



- 1 - 



EXEC(2) 



(C Software Development Set) 



EXEC(2) 



NAME 

exec: execl, execv, execle, execve, execlp, execvp - execute a file 
SYNOPSIS 

int execl (path, argO, argl, argn, (char *)0) 
char *path, *argO, *argl, *argn; 

int execv (path, argv) 
char *path, *argv[ ]; 

int execle (path, argO, argl, argn, (char *)0, envp) 
char *path, *argO, *argl, *argn, *envp[ ]; 

int execve (path, argv, envp) 
char *path, *argv[ ], *envp[ ]; 

int execlp (file, argO, argl, argn, (char *)0) 
char *file, *argO, *argl, *argn; 

int execvp (file, argv) 
char *file, *argv[ ]; 

DESCRIPTION 

The exec system call in all its forms transforms the calling process into a 
new process. The new process is constructed from an ordinary, executable 
file called the new process file. This file consists of a header [see fl.0Mf(4)], a 
text segment, and a data segment. The data segment contains an initialized 
portion and an uninitialized portion (bss). There can be no return from a 
successful exec because the calling process is overlaid by the new process. 

When a C program is executed, it is called as follows: 

main (argc, argv, envp) 
int argc; 

char **argv, **envp; 

where argc is the argument count, argv is an array of character pointers to 
the arguments themselves, and envp is an array of character pointers to the 
environment strings. As indicated, argc is conventionally at least one, and 
the first member of the array points to a string containing the name of the 
file. 

The path argument points to a path name that identifies the new process 
file. 

The file argument points to the new process file. The path prefix for this 
file is obtained by a search of the directories passed as the environment line 
"PATH =" [see environ{5)]. The environment is supplied by the shell [see 
sh{l)]. 

argO, argl, argn are pointers to null-terminated character strings. These 
strings constitute the argument list available to the new process. By con- 
vention, at least argO must be present and point to a string that is the same 
as path (or its last component). 

argv is an array of character pointers to null-terminated strings. These 
strings constitute the argument list available to the new process. By 
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convention, argv must have at least one member, and it must point to a 
string that is the same as path (or its last component), argv is terminated by 
a null pointer. 

envp is an array of character pointers to null-terminated strings. These 
strings constitute the environment for the new process, envp is terminated 
by a null pointer. For execl and execv, the C run-time start-off routine 
places a pointer to the environment of the calling process in the global cell: 
extern char **environ; 

and it is used to pass the environment of the calling process to the new pro- 
cess. 

File descriptors open in the calling process remain open in the new process, 
except for those whose close-on-exec flag is set; see fcntl(2). For those file 
descriptors that remain open, the file pointer is unchanged. 

Signals set to terminate the calling process will be set to terminate the new 
process. Signals set to be ignored by the calling process will be set to be 
ignored by the new process. Signals set to be caught by the calling process 
will be set to terminate the new process; see signal{2). 

For signals set by sigset{l\ exec will ensure that the new process has the 
same system signal action for each signal type whose action is SIG_DFL, 
SIG_IGN, or SIG-_HOLD as the calling process. However, if the action is 
to catch the signal, then the action will be reset to SIG_DFL, and any pend- 
ing signal for this type will be held. 

If the set-user-ID mode bit of the new process file is set [see chmod{l)\ exec 
sets the effective user ID of the new process to the owner ID of the new pro- 
cess file. Similarly, if the set-group-ID mode bit of the new process file is 
set, the effective group ID of the new process is set to the group ID of the 
new process file. The real user ID and real group ID of the new process 
remain the same as those of the calling process. 

The shared memory segments attached to the calling process will not be 
attached to the new process [see shmop(l)\. 

Profiling is disabled for the new process; see profit (2). 

The new process also inherits the following attributes from the calling pro- 
cess: 

nice value [see nice (2)] 

process ID 

parent process ID 

process group ID 

semadj values [see semop{2)] 

tty group ID [see exit{2) and signal(2)] 

trace flag [see ptrace{2) request 0] 

time left until an alarm clock signal [see alarm(2)] 

current working directory 

root directory 

file mode creation mask [see umask{2)] 
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file size limit [see ulimit{2)] 

utime, stime, cutime, and cstime [see tiines{2)] 

file-locks [see fcntl(2) and lockf(3C)] 

The exec system call will fail and return to the calling process if one or more 
of the following is true: 

[ENOENT] One or more components of the new process path name of 

the file do not exist. 

[ENOTDIR] A component of the new process path of the file prefix is 
not a directory. 

[EACCES] Search permission is denied for a directory listed in the 

new process file's path prefix. 

[EACCES] The new process file is not an ordinary file. 

[EACCES] The new process file mode denies execution permission. 

[ENOEXEC] The exec is not an execlp or execvp , and the new process 
file has the appropriate access permission but an invalid 
magic number in its header. 

[ETXTBSY] The new process file is a pure procedure (shared text) file 

that is currently open for writing by some process. 

[ENOMEM] The new process requires more memory than is allowed by 
the system-imposed maximum MAXMEM. 

[E2BIG] The number of bytes in the new process's argument list is 

greater than the system-imposed limit of 5120 bytes. 

[EFAULT] Required hardware is not present. 

[EFAULT] Path, argv, or envp point to an illegal address. 

[EAGAIN] Not enough memory. 

[ELIBACC] Required shared library does not have execute permission. 

[ELIBEXEC] Trjdng to exec{2) a shared library directly. 

[EINTR] A signal was caught during the exec system call. 

[ENOLINK] Path points to a remote machine and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

alarm(2), exit(2), fcntl(2), fork{2), nice(2), ptrace(2), semop(2), signal(2), sig- 
set(2), times(2), ulimit(2), umask(2), lockf(3C), a.out(4), environ(5). 
sh(l) in the User's/System Administrator's Reference Manual. 

DIAGNOSTICS 

If exec returns to the calling process, an error has occurred; the return value 
will be -1 and errno will be set to indicate the error. 
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NAME 

exit, _exit - terminate process 

SYNOPSIS 

void exit (status) 
int status; 
void _exit (status) 
int status; 

DESCRIPTION 

The exit system call terminates the calling process with the following conse- 
quences: 

All of the file descriptors open in the calling process are closed. 

If the parent process of the calling process is executing a wait, it is notified 
of the calling process's termination and the low order eight bits (i.e., bits 
0377) of status are made available to it [see wait{2)]. 

If the parent process of the calling process is not executing a wait, the cal- 
ling process is transformed into a zombie process. A zombie process is a 
process that only occupies a slot in the process table. It has no other space 
allocated either in user or kernel space. The process table slot that it occu- 
pies is partially overlaid with time accounting information (see 
<sys/proc.h>) to be used by times. 

The parent process ID of all of the calling processes' existing child processes 
and zombie processes is set to 1. This means the initialization process [see 
intro{2)] inherits each of these processes. 

Each attached shared memory segment is detached and the value of 
shm^nattach in the data structure associated with its shared memory iden- 
tifier is decremented by 1. 

For each semaphore for which the calling process has set a semadj value 
[see semop{2)], that semadj value is added to the semval of the specified 
semaphore. 

If the process has a process, text, or data lock, an unlock is performed [see 
plock(2)]. 

An accounting record is written on the accounting file if the system's 
accounting routine is enabled [see acct (2)]. 

If the process ID, tty group ID, and process group ID of the calling process 
are equal, the SIGHUP signal is sent to each process that has a process 
group ID equal to that of the calling process. 

A death of child signal is sent to the parent. 

The C function exit may cause cleanup actions before the process exits. The 
function -^xit circumvents all cleanup. 

SEE ALSO 

acct(2), intro(2), plock(2), semop(2), signal(2), sigset(2), wait(2). 

DIAGNOSTICS 

None. There can be no return from an exit system call. 
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NAME 

fcntl - file control 

SYNOPSIS 

#include <fcntl.h> 

int fcntl (fildes, cmd, arg) 
int fildes, cmd; 

DESCRIPTION 

The fcntl system call provides for control over open files. The fildes argu- 
ment is an open file descriptor obtained from a creat, open, dup, fcntl, or 
pipe system call. The data type and value of arg are specific to the type of 
command specified by cmd. The symbolic names for commands and file 
status flags are defined by the <fcntl.h> header file. 

The commands available are: 

F_DUPFD Return a new file descriptor as foUovy^s: 

Lowest numbered available file descriptor greater than or 
equal to arg. 

Same open file (or pipe) as the original file. 

Same file pointer as the original file (i.e., both file descrip- 
tors share one file pointer). 
Same access mode (read, write, or read/write). 

Same file status flags (i.e., both file descriptors share the 
same file status flags). 

The close-on-exec flag associated with the new file 
descriptor is set to remain open across exec{T) system 
calls. 

F_GETFD Get the close-on-exec flag associated with the file descrip- 

tor fildes. If the low-order bit is 0, the file will remain 
open across exec; otherwise the file will be closed upon 
execution of exec. 

F_SETFD Set the close-on-exec flag associated with fildes to the 

low-order bit of arg (0 or 1 as above). 

F_GETFL Get file status flags [see open{l)\. 

F_SETFL Set file status flags to arg. Only certain flags can be set 

[see/cnt/(5)]. 

The following commands are used for file-locking and record-locking. 
Locks may be placed on an entire file or segments of a file. 

F_GETLK 

Get the first lock that blocks the lock description given by the vari- 
able of type struct flock pointed to by arg. The information retrieved 
overwrites the information passed to fcntl in the flock structure. If 
no lock is found that would prevent this lock from being created, 
then the structure is passed back unchanged except for the lock type 
which will be set to F_UNLCK. 
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F_SETLK 

Set or clear a file segment lock according to the variable of type 
struct flock pointed to by arg [see fcntl{5)l The cmd F^SETLK is used 
to establish read (F_RDLCK) and write (F_WRLCK) locks, as well as 
remove either type of lock (F_UNLCK), If a read or write lock can- 
not be set, fcntl will return immediately with an error value of -1. 
F_SETLKW 

This cmd is the same as F^SETLK except that if a read or write lock 
is blocked by other locks, the process v^l sleep until the segment is 
free to be locked. 

A read lock prevents any process from write locking the protected area. 
More than one read lock may exist for a given segment of a file at a given 
time. The file descriptor on which a read lock is being placed must have 
been opened v^th read access. 

A write lock prevents any process from read-locking or write-locking the 
protected area. Only one write lock may exist for a given segment of a file 
at a given time. The file descriptor on which a write lock is being placed 
must have been opened with write access. 

The structure flock defined in the <fcntl.h> header file describes a lock. It 
describes the type (l-type), starting offset (l^whence), relative ofifset 
(l^tart), size (/_/ew), and process-ID (l—pid): 

short l^type; /* F_RDLCK, F_WRLCK, F_UNLCK */ 
short l-jivhence; /* flag for starting offset */ 
long l^tart; /* relative offset in bytes */ 
long l^len; /* if then until EOF */ 
short l—pid; /* returned with F_GETLK */ 

The value of l^whence is 0, 1, or 2 to indicate that the relative offset, l^tart 
bytes, will be measured from the start of the file, current position, or end of 
file, respectively. The value of l^en is the number of consecutive bytes to 
be locked. The process id is used only with the F_GETLK cmd to return the 
values for a blocking lock. Locks may start and extend beyond the current 
end of a file, but may not be negative relative to the beginning of the file. 
A lock may be set to always extend to the end of file by setting l^len to 
zero (0). If such a lock also has l-xvhence and l^tart set to zero (0), the 
whole file will be locked. Changing or unlocking a segment from the mid- 
dle of a larger locked segment leaves two smaller segments for either end. 
Locking a segment that is already locked by the calling process causes the 
old lock type to be removed and the new lock type to take effect. All locks 
associated vsdth a file for a given process are removed when a file descriptor 
for that file is closed by that process or the process holding that file descrip- 
tor terminates. Locks are not inherited by a child process in a fork{2) system 
call. 

When mandatory file and record locking is active on a file [see chmod{2)], 
read and write system calls issued on the file will be affected by the record 
locks in effect. 
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The fcntl system call will fail if one or more of the following is true: 



[EBADF] 
[EINVAL] 



[EINVAL] 



[EACCES] 



[ENOLCK] 



[EMFILE] 



[EBADF] 



[EBADF] 



[EDEADLK] 



[EFAULT] 

[EINTR] 
[ENOLINK] 



The fildes argument is not a valid open file descriptor. 

The cmd argument is F_DUPFD. The arg argument is either 
negative, or greater than or equal to the configured value 
for the maximum number of open file descriptors allowed 
each user. 



The cmd argument is F_GETLK, F_SETLK, or SETLKW and 
arg or the data it points to is not valid. 

The cmd argument is F_SETLK, the type of lock {l^type) is a 
read (F_RDLCK) lock, and the segment of a file to be locked 
is already write locked by another process or the type is a 
write (F_WRLCK) lock and the segment of a file to be 
locked is already read or write locked by another process. 

The cmd argument is F_SETLK or F_SETLKW, the type of 
lock is a read or write lock, and there are no more record 
locks available (too many file segments locked) because the 
system maximum has been exceeded. 

The cmd argument is F_DUPFD and file-descriptors are 
currently open in the calling-process. 

The cmd argument is F_SETLK or F_SETLKW, the type of 
lock {l-.type) is a read-lock (F_JRDLCK), and fildes is not a 
valid file-descriptor open for reading. 

The cmd argument is F_SETLK or F_SETLKW, the type of 
lock (I— type) is a write-lock (F_WRLCK), and fildes is not a 
valid file-descriptor open for writing. 

The cmd argument is F_SETLKW, the lock is blocked by 
some lock from another process, and putting the calling- 
process to sleep, waiting for that lock to become free, 
would cause a deadlock. 

The cmd argument is F_SETLK, arg points outside the pro- 
gram address space. 

A signal was caught during the fcntl system call. 

Fildes is on a remote machine and the link to that machine 
is no longer active. 

SEE ALSO 

close(2), creat(2), dup(2), exec(2), fork(2), open(2), pipe(2), fcntl(5). 
DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 
F_DUPFD A new file descriptor. 

F_GETFD Value of flag (only the low-order bit is defined). 

F_SETFD Value other than -1. 
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F^GETFL 
F_SETFL 
F_GETLK 
F_SETLK 
F_SETLKW 



Value of file flags. 
Value other than -1. 
Value other than -1. 
Value other than -1. 
Value other than -1. 



Otherwise, a value of -1 is returned, and ermo is set to indicate the error. 
WARNINGS 

Because in the future the variable ermo will be set to EAGAIN rather than 
EACCES when a section of a file is already locked by another process, port- 
able application programs should expect and test for either value. 
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NAME 

fork - create a new process 

SYNOPSIS 

int fork 

DESCRIPTION 

The fork system call causes creation of a new process. The new process 
(child process) is an exact copy of the calling process (parent process). This 
means the child process inherits the following attributes from the parent 
process: 

environment 

close-on-exec flag [see exec (2)] 

signal handling settings (i.e., SIG-DFL, SIG_JGN, SIG_HOLD, func- 
tion address) 
set-user-ID mode bit 
set-group-ID mode bit 
profiling on/off status 
nice value [see nice {2)] 

all attached shared memory segments [see shmop{2)] 

process group ID 

tty group ID [see exit (2)] 

current working directory 

root directory 

file mode creation mask [see umask{2)] 
file size limit [see ulimit(2)] 

The child process differs from the parent process in the following ways: 
The child process has a unique process ID. 

The child process has a different parent process ID (i.e., the process 
ID of the parent process). 

The child process has its own copy of the parent's file descriptors. 
Each of the child's file descriptors shares a common file pointer with 
the corresponding file descriptor of the parent. 

All semadj values are cleared [see semop{2)]. 

Process locks, text locks, and data locks are not inherited by the 
child [see plock(2)]. 

The child process's utime, stime, cutime, and cstime are set to 0. 
The time left until an alarm clock signal is reset to 0. 

The fork system call will fail and no child process will be created if one or 
more of the following is true: 

[EAGAIN] The system-imposed limit on the total number of processes 

under execution would be exceeded. 

[EAGAIN] The system-imposed limit on the total number of processes 

under execution by a single user would be exceeded. 
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[EAGAIN] Total amount of system memory available when reading 

via rav^ lO is temporarily insufficient. 

[ENOMEM] The process requires more space than the system is able to 
supply. 

SEE ALSO 

exec(2), nice(2), plock(2), ptrace(2), semop(2), shmop(2), signal(2), sigset(2), 
times(2), ulimit(2), umask(2), v^ait(2). 

DIAGNOSTICS 

Upon successful completion, fork returns a value of to the child process 
and returns the process ID of the child process to the parent process. Other- 
wise, a value of -1 is returned to the parent process, no child process is 
created, and ermo is set to indicate the error. 
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NAME 

getdents - read directory entries and put in a file-system-independent for- 
mat 

SYNOPSIS 

#include <sys/dirent.h> 

int getdents (Hides, buf, nbyte) 
int tildes; 
char *bni; 
unsigned nbyte; 

DESCRIPTION 

The fildes argument is a file descriptor obtained from an open (2) or dup{2) 
system call. 

The getdents system call attempts to read nbyte bytes from the directory 
associated with fildes and to format them as file system independent direc- 
tory entries in the buffer pointed to by buf. Since the file-system- 
independent directory entries are of variable length, in most cases the actual 
number of bytes returned will be strictly less than nbyte. 

The file-system-independent directory entry is specified by the dirent struc- 
ture. For a description of this see dirent (4), 

On devices capable of seeking, getdents starts at a position in the file given 
by the file pointer associated with fildes. Upon return from getdents, the file 
pointer is incremented to point to the next directory entry. 

This system call was developed in order to implement the readdir{3X) rou- 
tine [for a description see directory {3X)], and should not be used for other 
purposes. 

The getdents system call will fail if one or more of the following is true: 

[EBADF] Fildes is not a valid file descriptor open for reading. 

[EFAULT] Buf points outside the allocated address space. 

[EINVAL] nbyte is not large enough for one directory entry. 

[ENOENT] The current file pointer for the directory is not located at a 

valid entry. 

[ENOLINK] Fildes points to a remote machine and the link to that 
machine is no longer active. 

[ENOTDIR] Fildes is not a directory. 

[EIO] An I/O error occurred while accessing the file system. 

SEE ALSO 

directory(3X), dirent(4). 

DIAGNOSTICS 

Upon successful completion a non-negative integer is returned, indicating 
the number of bytes actually read. A value of indicates the end of the 
directory has been reached. If the system call failed, a -1 is returned, and 
ermo is set to indicate the error. 
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NAME 

getmsg - get next message off a stream 

SYNOPSIS 

#include <stropts.h> 

int getmsg(fd, ctlptr, dataptr, flags) 
int fd; 

struct strbuf *ctlptr; 
struct strbuf *dataptr; 
int *flags; 

DESCRIPTION 

The getmsg system call retrieves the contents of a message [see intro(2)] 
located at the stream head read queue from a STREAMS file, and places the 
contents into user-specified buffer(s). The message must contain either a 
data part, a control part, or both. The data and control parts of the message 
are placed into separate buffers, as described below. The semantics of each 
part is defined by the STREAMS module that generated the message. 

The fd argument specifies a file descriptor referencing an open stream. 
Ctlptr and dataptr each point to a strbuf structure which contains the follow- 
ing members: 

int maxlen; /* maximum buffer length */ 
int len; /* length of data */ 

char *buf; /* ptr to buffer */ 

where buf points to a buffer in which the data or control information is to 
be placed, and maxlen indicates the maximum number of bytes this buffer 
can hold. On return, len contains the number of bytes of data or control 
information actually received, or is if there is a zero-length control or data 
part, or is -1 if no data or control information is present in the message. 
Flags may be set to the values or RS_HIPRI and is used as described 
below. 

The ctlptr argument is used to hold the control part from the message and 
dataptr is used to hold the data part from the message. If ctlptr (or dataptr) 
is NULL or the maxlen field is -1, the control (or data) part of the message is 
not processed and is left on the stream head read queue, and len is set to -1. 
If the maxlen field is set to and there is a zero-length control (or data) 
part, that zero-length part is removed from the read queue and len is set to 
0. If the maxlen field is set to and there are more than zero bytes of con- 
trol (or data) information, that information is left on the read queue and len 
is set to 0. If the maxlen field in ctlptr or dataptr is less than, respectively, 
the control or data part of the message, maxlen bytes are retrieved. In this 
case, the remainder of the message is left on the stream head read queue and 
a non-zero return value is provided, as described below under DIAGNOS- 
TICS. If information is retrieved from a priority message, flags is set to 
RS_HIPRI on return. 
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By default, getmsg processes the first priority or non-priority message avail- 
able on the stream head read queue. However, a user may choose to 
retrieve only priority messages by setting flags to RS_HIPRI. In this case, 
getmsg will only process the next message if it is a priority message. 

If 0_NDELAY has not been set, getmsg blocks until a message, of the type(s) 
specified by flags (priority or either), is available on the stream head read 
queue. If 0_NDELAY has been set and a message of the specified type(s) is 
not present on the read queue, getmsg fails and sets ermo to EAGAIN. 

If a hangup occurs on the stream from which messages are to be retrieved, 
getmsg will continue to operate normally, as described above, until the 
stream head read queue is empty. Thereafter, it will return in the len fields 
of ctlptr and dataptr. 

The getmsg system call fails if one or more of the following is true: 

[EAGAIN] The 0_NDELAY flag is set, and no messages are available. 

[EBADF] Fd is not a valid file descriptor open for reading. 

[EBADMSG] Queued message to be read is not valid for getmsg. 

[EFAULT] Ctlptr, dataptr, or flags points to a location outside the allo- 

cated address space. 

[EINTR] A signal was caught during the getmsg system call. 

[EINVAL] An illegal value was specified in flags, or the stream refer- 

enced by fd is linked under a multiplexer. 

[ENOSTR] A stream is not associated with fd. 

A getmsg can also fail if a STREAMS error message had been received at the 
stream head before the call to getmsg. The error returned is the value con- 
tained in the STREAMS error message. 

SEE ALSO 

intro(2), read(2), poll(2), putmsg(2), write(2). 

STREAMS Primer 

STREAMS Programmer's Guide 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. A value of 
indicates that a full message was read successfully. A return value of 
MORECTL indicates that more control information is waiting for retrieval. A 
return value of MOREDATA indicates that more data is waiting for retrieval. 
A return value of MORECTLlMOREDATA indicates that both types of infor- 
mation remain. Subsequent getmsg calls will retrieve the remainder of the 
message. 
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NAME 

getpid, getpgrp, getppid - get process, process group, and parent process IDs 

SYNOPSIS 

int getpid () 

int getpgrp () 

int getppid () 

DESCRIPTION 

The getpid system call returns the process ID of the calling process. 
The getpgrp system call returns the process group ID of the calling process. 
The getppid system call returns the parent process ID of the calling process. 
SEE ALSO 

exec(2), fork(2), intro(2), setpgrp(2), signal(2). 
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NAME 

getuid, geteuid, getgid, getegid - get real user, effective user, real group, and 
effective group IDs 

SYNOPSIS 

unsigned short getuid () 

unsigned short geteuid () 

unsigned short getgid () 

unsigned short getegid () 

DESCRIPTION 

The getuid system call returns the real user ID of the calling process. 

The geteuid system call returns the effective user ID of the calling process. 

The getgid system call returns the real group ID of the calling process. 

The getegid system call returns the effective group ID of the calling process. 

SEE ALSO 

intro(2), setuid(2). 
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NAME 

ioctl - control device 

SYNOPSIS 

int ioctl (Hides, request, arg) 
int Hides, request; 

DESCRIPTION 

The ioctl system call performs a variety of control functions on devices and 
STREAMS. For non-STREAMS files, the functions performed by this call are 
device-specific control functions. The arguments request and arg are passed 
to the file designated by fildes and are interpreted by the device driver. This 
control is infrequently used on non-STREAMS devices, with the basic 
input/output functions performed through the read{l) and write{l) system 
calls. 

For STREAMS files, specific functions are performed by the ioctl call as 
described in streamio(7). 

Fildes is an open file descriptor that refers to a device. Request selects the 
control function to be performed and will depend on the device being 
addressed. Arg represents additional information that is needed by this 
specific device to perform the requested function. The data type of arg 
depends upon the particular control request, but it is either an integer or a 
pointer to a device-specific data structure. 

In addition to device-specific and STREAMS functions, generic functions are 
provided by more than one device driver, for example, the general terminal 
interface [see termio{7)]. 

The ioctl system call will fail for any type of file if one or more of the fol- 
lowing is true: 

[EBADF] Fildes is not a valid open file descriptor. 

[ENOTTY] Fildes is not associated with a device driver that accepts 
control functions. 

[EINTR] A signal was caught during the ioctl system call. 

The ioctl system call will also fail if the device driver detects an error. In 
this case, the error is passed through ioctl without change to the caller. A 
particular driver might not have all of the following error cases. Other 
requests to device drivers vsdll fail if one or more of the following is true: 

[EFAULT] Request requires a data transfer to or from a buffer pointed 

to by arg, but some part of the buffer is outside the 
process's allocated space. 

[EINVAL] Request or arg is not valid for this device. 

[EIO] Some physical I/O error has occurred. 

[ENXIO] The request and arg are valid for this device driver, but the 

service requested cannot be performed on this particular 
subdevice. 
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[ENOLINK] Fildes is on a remote machine and the link to that machine 
is no longer active. 

STREAMS errors are described in $treamio(7). 

SEE ALSO 

streamio(7), termio(7) in the User's/System Administrator's Reference Manual 
DIAGNOSTICS 

Upon successful completion, the value returned depends upon the device 
control function, but must be a non-negative integer. Otherwise, a value of 
-1 is returned, and errno is set to indicate the error. 
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NAME 

kill - send a signal to a process or a group of processes 

SYNOPSIS 

#include <signal.h> 

int kill (pid, sig) 
int pid, sig; 

DESCRIPTION 

The kill system call sends a signal to a process or a group of processes. The 
process or group of processes to which the signal is to be sent is specified 
by pid. The signal that is to be sent is specified by sig and is either one 
from the list given in signal{2) or 0. If sig is (the null signal), error check- 
ing is performed but no signal is actually sent. This can be used to check 
the validity of pid. 

The real or effective user ID of the sending process must match the real or 
effective user ID of the receiving process, unless the effective user ID of the 
sending process is super-user. 

The processes with a process ID of and a process ID of 1 are special 
processes [see intro{2)] and will be referred to below as procO and prod, 
respectively. 

If pid is greater than zero, sig will be sent to the process whose process ID is 
equal to pid. Pid may equal 1. 

If pid is 0, sig will be sent to all processes excluding procO and prod whose 
process group ID is equal to the process group ID of the sender. 

If pid is -1 and the effective user ID of the sender is not super-user, sig will 
be sent to all processes excluding procO and prod whose real user ID is 
equal to the effective user ID of the sender. 

If pid is -1 and the effective user ID of the sender is super-user, sig will be 
sent to all processes excluding procO and prod. 

If pid is negative but not -1, sig will be sent to all processes whose process 
group ID is equal to the absolute value of pid. 

The kill system call will fail and no signal will be sent if one or more of the 
following is true: 

[EINVAL] Sig is not a valid signal number. 

[EINVAL] Sig is SIGKILL and pid is 1 (procl). 

[ESRCH] No process can be found corresponding to that specified by 

pid. 

[EPERM] The user ID of the sending process is not super-user, and its 

real or effective user ID does not match the real or effective 
user ID of the receiving process. 

SEE ALSO 

getpid(2), setpgrp{2), signal(2), sigset(2). 

kill(l) in the User's /System Administrator's Reference Manual. 
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DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and ermo is set to indicate the error. 
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NAME 

link - link to a file 

SYNOPSIS 

int link (pathl, path2) 
char *pathl, ^pathZ; 

DESCRIPTION 

The pathl argument points to a path name naming an existing file. The 
pathl argument points to a path name naming the new directory entry to be 
created. The link system call creates a new link (directory entry) for the 
existing file. 

The link system call will fail and no link will be created if one or more of 
the following is true: 

[ENOTDIR] A component of either path prefix is not a directory. 

[ENOENT] A component of either path prefix does not exist. 

[EACCES] A component of either path prefix denies search permis- 

sion. 

[ENOENT] The file named by pathl does not exist. 

[EEXIST] The link named by pathl exists. 

[EPERM] The file named by pathl is a directory and the effective 

user ID is not super-user. 

[EXDEV] The link named by pathl and the file named by pathl are 

on different logical devices (file systems). 

[ENOENT] Pathl points to a null path name. 

[EACCES] The requested link requires writing in a directory with a 

mode that denies write permission. 

[EROFS] The requested link requires writing in a directory on a 

read-only file system. 

[EFAULT] Path points outside the allocated address space of the pro- 

cess. 

[EMLINK] The maximum number of links to a file would be exceeded. 

[EINTR] A signal was caught during the link system call. 

[ENOLINK] Path points to a remote machine and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

[ENOSPC] The directory containing the link cannot be extended. 

SEE ALSO 

unlink(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and ermo is set to indicate the error. 
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NAME 

Iseek - move read/ write file pointer 

SYNOPSIS 

#include <unistd.h> 

long Iseek (fildes, offset, whence) 
int fildes; 
long offset; 
int whence; 

DESCRIPTION 

The fildes argument is a file descriptor returned from a creat, open, dup, or 
fcntl system call. The Iseek system call sets the file pointer associated with 
fildes as follows: 

If whence is 0, the pointer is set to offset bytes. 

If whence is 1, the pointer is set to its current location plus offset. 

If whence is 2, the pointer is set to the size of the file plus offset. 

Symbolic constants for whence are defined in the <unistd.h> header file: 
Name Description 

SEEK_SET Set file-pointer equal to offset bytes. 

SEEK_CUR Set file-pointer to current location plus offset. 
SEEIC-END Set file-pointer to EOF plus offset. 

Upon successful completion, the resulting pointer location, as measured in 
bytes from the beginning of the file, is returned. Note that if fildes is a 
remote file descriptor and offset is negative, Iseek will return the file pointer 
even if it is negative. 

Iseek will fail and the file pointer will remain unchanged if one or more of 
the following is true: 

[EBADF] Fildes is not an open file descriptor. 

[ESPIPE] Fildes is associated with a pipe or fifo. 

[EINVAL and SIGSYS signal] 

Whence is not 0, 1, or 2. 

[EINVAL] Fildes is not a remote file descriptor, and the resulting file 

pointer would be negative. 

Some devices are incapable of seeking. The value of the file pointer associ- 
ated with such a device is undefined. 

SEE ALSO 

creat(2), dup(2), fcntl(2), open(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer indicating the file 
pointer value is returned. Otherwise, a value of -1 is returned, and errno is 
set to indicate the error. 
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NAME 

mkdir - make a directory 

SYNOPSIS 

#include <sys/types.h> 
#include <8ys/stat.h> 

int mkdir (path, mode) 
char *path; 
int mode; 

DESCRIPTION 

The routine mkdir creates a new directory with the name path. The argu- 
ment mode specifies the initial mode of the new directory. The protection 
bits of the argument mode are modified by the process file mode creation 
mask [see umask{2)]. The value of the argument mode should be the logical 
OR of the values of the desired permissions: 

Name Description 



S_IREAD 


Read by owner 


S_IWRITE 


Write by owner 


S_IEXEC 


Execute (search) by owner 


S-JRGRP 


Read by group 


S_IWGRP 


Write by group 


S_IXGRP 


Execute (search) by group 


SJROTH 


Read by others (i.e., anyone else) 


S_IWOTH 


Write by others 


S-JXOTH 


Execute (search) by others 



The directory's owner ID is set to the process's effective user ID. The 
directory's group ID is set to the process's effective group ID. The newly 
created directory is empty with the possible exception of entries for "." 
and mkdir will fail and no directory will be created if one or more of 

the following is true: 

[ENOTDIR] A comppifient of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[ENOLINK] Path points to a remote machine and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 
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[EACCES] 

[ENOENT] 
[EEXIST] 
[EROFS] 
[EFAULT] 

[EMLINK] 



Either a component of the path prefix denies search permis- 
sion, or write permission is denied on the parent directory 
of the directory to be created. 

The path is longer than the maximum allowed. 

The named file already exists. 

The path prefix resides on a read-only file system. 

Path points outside the allocated address space of the pro- 



cess. 



The maximum number of links to the parent directory 
would be exceeded. 

An I/O error has occurred while accessing the file system. 



[EIO] 
DIAGNOSTICS 

Upon successful completion^ a value of is returned. Otherwise, a value of 
-1 is returned, and errno is set to indicate the error. 
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NAME 

mknod - make a directory or a special or ordinary file or a FIFO 

SYNOPSIS 

#include <8ys/types.h> 
#include <sy8/stat.h> 

int mknod (path, mode, dev) 
char "(path; 
int mode, dev; 

DESCRIPTION 

The mknod system call creates a new file named by the path name pointed 
to by path. The mode of the new file is initialized from mode. Where the 
value of mode is interpreted as follows: 

0170000 file type; one of the following: 

0010000 fifo special 

0020000 character special 

0040000 directory 

0060000 block special 

0100000 or 0000000 ordinary file 

0004000 set user ID on execution 

00020#0 set group ID on execution if # is 7, 5, 3, or 1 

enable mandatory file/record locking if # is 6, 4, 2, or 

0001000 save text image after execution 

0000777 access permissions; constructed from the following: 

0000400 read by owner 
0000200 write by owner 

0000100 execute (search on directory) by owner 
0000070 read, write, execute (search) by group 
0000007 read, write, execute (search) by others 



Symbolic constants defining the value of the argument mode are in the 
<sys/stath> header file and should be used to construct mode. The value 
of the argument mode should be the logical OR of the values of the desired 
permissions: 



Name 


Description 


S_IFMT 


file type; one of the following: 


S_IFIFO 


FIFO-special 


S_IFCHR 


character-special 


S_IFDIR 


directory node 


S-IFBLK 


block-special 


S_IFREG 


ordinary-file 
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S_JSUID 


set user-ID on execution 


S-JSGID 


set group-ID on execution 


S_JSVTX 


(reserved) 


S_JENFMT 


record-locking enforced 


S^RUSR 


read by owner 


S_IWUSR 


write by owner 


S_IXUSR 


execute (search) by owner 


S_IRGRP 


read by group 


S_JWGRP 


write by group 


S_IXGRP 


execute (search) by group 


S-J[ROTH 


read by others (i.e., anyone else) 


S-JWOTH 


write by others 


S_IXOTH 


execute (search) by others 



The owner ID of the file is set to the effective user ID of the process. The 
group ID of the file is set to the effective group ID of the process. 

Values of mode other than those above are undefined and should not be 
used. The low-order 9 bits of mode are modified by the process's file mode 
creation mask: all bits set in the process's file mode creation mask are 
cleared [see umask{2)]. If mode indicates a block or character special file, 
dev is a configuration-dependent specification of a character or block I/O 
device. If mode does not indicate a block special or character special device, 
dev is ignored. 

The mknod routine may be invoked only by the super-user for file types 
other than FIFO special. 

The mknod routine will fail and the new file will not be created if one or 
more of the following is true: 

[EPERM] The effective user ID of the process is not super-user. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[EROFS] The directory in which the file is to be created is located on 

a read-only file system. 

[EEXIST] The named file exists. 

[EFAULT] Path points outside the allocated address space of the pro- 

cess. 

[ENOSPC] No space is available. 

[EINTR] A signal was caught during the mknod system call. 

[ENOLINK] Path points to a remote machine and the link to that 
machine is no longer active. 
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[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

chmod(2), exec(2), umask{2), fs(4). 

mkdir(l) in the User's /System Administrator's Reference Manual, 
DIAGNOSTICS 

Upon successful completion a value of is returned. Otherwise, a value of 
-1 is returned, and ermo is set to indicate the error. 

WARNING 

If mknod is used to create a device in a remote directory (Remote File Shar- 
ing), the major and minor device numbers are interpreted by the server. 
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NAME 

mount - mount a file system 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/inount.h> 

int mount (spec, dir, mflag, fstyp, dataptr, datalen) 
char *spec, *dir; 
int mflag, fstyp; 
char ♦dataptr; 
int datalen; 

DESCRIPTION 

mount requests that a removable file system contained on the block special 
file identified by spec be mounted on the directory identified by dir. Spec 
and dir are pointers to path names, fstyp is the file system type number. 
The sysfs{2) system call can be used to determine the file system type 
number. Note that if both the MS_DATA and MS_FSS flag bits of mflag 
are off, the file system type will default to the root file system type. Only if 
either flag is on will fstyp be used to indicate the file system type. 

If the MS—DATA flag is set in mflag, the system expects the dataptr and 
datalen arguments to be present. Together they describe a block of file- 
system specific data at address dataptr of length datalen. This is interpreted 
by file-system specific code within the operating system and its format 
depends upon the file system type. A particular file system type may not 
require this data, in which case dataptr and datalen should both be zero. 
Note that MS_FSS is obsolete and will be ignored if MS_DATA is also set, 
but if MS_FSS is set and MS_DATA is not, dataptr and datalen are both 
assumed to be zero. 

Upon successful completion, references to the file dir will refer to the root 
directory on the mounted file system. 

The low-order bit of mflag is used to control write permission on the 
mounted file system; if 1, writing is forbidden, otherwise writing is permit- 
ted according to individual file accessibility. 

mount may be invoked only by the super-user. It is intended for use only 
by the mount(lM) utility. 

mount vdll fail if one or more of the following is true: 

[EPERM] The effective user ID is not super-user. 

[ENOENT] Any of the named files does not exist. 

[ENOTDIR] A component of a path prefix is not a directory. 

[EREMOTE] Spec is remote and cannot be mounted. 

[ENOLINK] Path points to a remote machine and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 
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[ENOTBLK] Spec is not a block special device. 

[ENXIO] The device associated with spec does not exist. 

[ENOTDIR] Dir is not a directory. 

[EFAULT] Spec or dir points outside the allocated address space of the 

process. 

[EBUSY] Dir is currently mounted on, is someone's current working 

directory, or is otherwise busy. 

[EBUSY] The device associated with spec is currently mounted. 

[EBUSY] There are no more mount table entries. 

[EROFS] Spec is write-protected and mflag requests write permission. 

[ENOSPC] The file system state in the super-block is not FsOKAY and 

mflag requests write permission. 

[EINVAL] The super-block has an invalid magic number or the fstyp is 

invalid or mflag is not valid. 

SEE ALSO 

sysfs(2), umount(2). 

mount(lM), fs(4) in the User's/System Administrator's Reference Manual 
DIAGNOSTICS 

Upon successful completion a value of is returned. Otherwise, a value of 
-1 is returned, and ermo is set to indicate the error. 
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NAME 

msgctl - message control operations 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/msg.h> 

int msgctl (msqid, cmd, buf) 
int msqid, cmd; 
struct msqid_ds *buf; 

DESCRIPTION 

The msgctl system call provides a variety of message control operations as 
specified by cmd. The following cmds are available: 

IPC__STAT Place the current value of each member of the data struc- 
ture associated with msqid into the structure pointed to by 
buf. The contents of this structure are defined in intro(2). 
{READ} 

IPC_SET Set the value of the following members of the data struc- 

ture associated with msqid to the corresponding value 
found in the structure pointed to by buf: 

msg_perm.uid 
msg_perm.gid 

msg_perm.mode /* only low 9 bits */ 
msg_qbytes 



This cmd can only be executed by a process that has an 
effective user ID equal to either that of super-user, or to the 
value of msg-.perm.cuid or msg_perm.uid in the data 
structure associated with msqid. Only super-user can raise 
the value of msg_qbytes. 

IPC-RMID Remove the message queue identifier specified by msqid 
from the system and destroy the message queue and data 
structure associated with it. This cmd can only be executed 
by a process that has an effective user ID equal to either 
that of super-user, or to the value of msg-_perm.cuid or 
msg_perm.uid in the data structure associated with msqid. 

The msgctl system call will fail if one or more of the foUov^ng is true: 

[EINVAL] The msqid argument is not a valid message queue identifier. 

[EINVAL] The cmd argument is not a valid command. 

[EACCES] The cmd argument is equal to IPC_STAT and {READ} 

operation permission is denied to the calling process [see 
intro{2)]. 

[EPERM] The cmd argument is equal to IPC_RMID or IPC_SET. The 

effective user ID of the calling process is not equal to that 
of super-user, or to the value of msg_perm.cuid or 
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insg-.perm.uid in the data structure associated with msqid. 

[EPERM] The cmd argument is equal to IPC-SET, an attempt is being 

made to increase to the value of msg— qbytes, and the 
effective user ID of the calling process is not equal to that 
of super-user. 

[EFAULT] The buf argument points to an illegal address. 

SEE ALSO 

intro(2), msgget(2), msgop(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and errno is set to indicate the error. 
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NAME 

msgget - get message queue 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/msg.h> 

int msgget (key, msgflg) 
key— t key; 
int msgflg; 

DESCRIPTION 

The msgget system call returns the message queue identifier associated with 
key. 

A message queue identifier and associated message queue and data structure 
[see intro{2)] are created for key if one of the following is true: 
The key argument is equal to IPC-PRIVATE. 

The key argument does not already have a message queue identifier 
associated with it, and (msgflg & IPC-CREAT) is "true". 

Upon creation, the data structure associated with the new message queue 

identifier is initialized as follows: 

Msg_perm.cuid, msg_.perm.uid, msg_perm.cgid, and 
ms^perm.gid are set equal to the effective user ID and effective 
group ID, respectively, of the calling process. 

The low-order 9 bits of msg_perm.mode are set equal to the low- 
order 9 bits of msgflg. 

Msg-qnum, msg_lspid, msg_lrpid, msg-stime, and msg_rtime 

are set equal to 0. 

Msg-ctime is set equal to the current time. 
Msg_qbytes is set equal to the system limit. 

The msgget system call will faU if one or more of the following is true: 

[EACCES] A message queue identifier exists for key, but operation per- 

mission [see intro(2)] as specified by the low-order 9 bits of 
msgflg would not be granted. 

[ENOENT] A message queue identifier does not exist for key and 

(msgflg & IPC-CREAT) is "false". 

[ENOSPC] A message queue identifier is to be created but the system- 

imposed limit on the maximum number of allowed message 
queue identifiers system wide would be exceeded. 

fEEXIST] A message queue identifier exists for key but [(msgflg & 

IPC-CREAT) & (msgflg & IPC-EXCL)] is "true". 

SEE ALSO 

intro(2), msgcd(2), msgop(2). 
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DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a message 
queue identifier, is returned. Otherwise, a value of -1 is returned, and err^o 
IS set to indicate the error. 
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NAME 

msgop: msgsnd, msgrcv - message operations 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/msg.h> 

int msgsnd (msqid, msgp, msgsz, msgflg) 
int msqid; 

struct msgbuf *msgp; 
int msgsz, msgflg; 

int msgrcv (msqid, msgp, msgsz, msgtyp, msgflg) 
int msqid; 

struct msgbuf *msgp; 
int msgsz; 
long msgtyp; 
int msgflg; 

DESCRIPTION . 

The msgsnd system call is used to send a message to the queue associated 
with the message queue identifier specified by msqid, {WRITE} Msgp points 
to a structure containing the message. This structure is composed of the fol- 
lowing members: 

long mtype; /* message type */ 

char mtext[]; /* message text */ 

The mtype integer is positive and can be used by the receiving process for 
message selection (see msgrcv below). The array mtext is any text of length 
msgsz bytes. The msgsz argument can range from to a system-imposed 
maximum. 

Msgflg specifies the action to be taken if one or more of the following is 
true: 

The number of bytes already on the queue is equal to msg^qbytes 
[see intro{2)]. 

The total number of messages on all queues system-wide is equal to 
the system-imposed limit. 

These actions are as follows: 

If {msgflg & IPC-NOWAIT) is "true", the message will not be sent 
and the calling process will return immediately. 

If {msgflg & IPC_NOWAIT) is "false", the calling process will 
suspend execution until one of the following occurs: 

The condition responsible for the suspension no longer 
exists, in which case the message is sent. 
The msqid argument is removed from the system [see 
msgctl{2)]. When this occurs, errno is set equal to EIDRM, 
and a value of -1 is returned. 
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The calhng process receives a signal that is to be caught 
In this case the message is not sent and the calling process 
resumes execution in the manner prescribed in signal{2). 

Ms^d will faU and no message will be sent if one or more of the following 

[EI^A^AL] Msqid is not a valid message queue identifier. 

[EACCES] Operation permission is denied to the calling process fsee 

intro(2)]. ° ^ 

[EINVAL] Mtype is less than 1. 

[EAGAIN] The message cannot be sent for one of the reasons cited 

above and (msgflg & IPCNOWAIT) is "true". 
[EINVAL] Mgs2 is less than zero or greater than the system-imposed 

[EFAULT] Msgp points to an illegal address. 

IirH",f"Tl"' completion, the following actions are taken with respect to 
the data struchire assoaated with msqid [see intro(2)]. 

Msg—qnum is incremented by 1. 

MsgJspid is set equal to the process ID of the calling process. 

Msg_stime is set equal to the current time. 
ShL'^^'^" a message from the queue associated with the message queue 
msJ^ fpFTm T? 1 T'?"^.«"<1 P^^'^ » in the structure pointfd to by 
msgp. {READ} This struchire is composed of the following members: 

long mt)^e; /* message type */ 
char mtext[]; /* message text */ 

'"''""^Se's type as specified by the sending process 
Tht J H*'"* °^ '"""'"Se. Msgsz specifies the size in bytes^f Zlt. 
The recen^ed message is truncated to msgsz bytes if it is larger than mss^sz 
and (msgflg & MSG_NOERROR) is "true". The truncated part of ?he mS- 
sage IS lost and no indication of the truncation is given to the calling pro- 

Msgtyp specifies the type of message requested as follows: 

If msgiyp is equal to 0, the first message on the queue is received. 
receS ^ ^^^^^'^ ^' *^ ^"^^ message of type msgtyp is 

If msgtyp is less than 0, the first message of the lowest type that is 
less than or equal to the absolute value of msgtyp is received. 

Ms^g specifies the action to be taken if a message of the desired type is not 
on the queue. These are as follows: lype is not 

If (msgflg & IPCJJOWAIT) is "true", the calling process will rehim 
immediately with a rehim value of -1 and ermo set to ENOMSG. 
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If (msgflg & IPC_NOWAIT) is "false", the calling process will 
suspend execution until one of the following occurs: 

A message of the desired type is placed on the queue. 
Msqid is removed from the system. When this occurs, 
ermo is set equal to EIDRM, and a value of -1 is returned. 

The calling process receives a signal that is to be caught. 
In this case a message is not received and the calling pro- 
cess resumes execution in the manner prescribed in sig- 
nal(2y 

Msgrcv will fail and no message will be received if one or more of the fol- 
lowing is true: 

[EINVAL] Msqid is not a valid message queue identifier, 

[EACCES] Operation permission is denied to the calling process. 

[EINVAL] Msgsz is less than 0. 

[E2BIG] Mtext is greater than msgsz and {msgflg & MSG_NOERROR) 

is "false". 

[ENOMSG] The queue does not contain a message of the desired type 
and (msgtyp & IPC_NOWAIT) is "true". 

[EFAULT] Msgp points to an illegal address. 

Upon successful completion, the following actions are taken with respect to 
the data struchire associated with msqid [see intro(2)]. 
Msg— qnum is decremented by 1. 

Msg-lrpid is set equal to the process ID of the calling process. 
Msg-Ttime is set equal to the current time. 

SEE ALSO 

intro(2), msgctl(2), msgget(2), signal(2). 

DIAGNOSTICS 

If msgsnd or msgrcv return due to the receipt of a signal, a value of -1 is 
rehimed to the calling process and ermo is set to EINTR. If they return due 
to removal of msqid from the system, a value of -1 is returned and ermo is 
set to EIDRM. 

Upon successful completion, the return value is as follows: 
Msgsnd returns a value of 0. 

Msgrcv returns a value equal to the number of bytes actually placed 
into mtext. 

Otherwise, a value of -1 is returned, and ermo is set to indicate the error. 
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NAME 

nice - change priority of a process 
SYNOPSIS 

int nice (incr) 
int incr; 

DESCRIPTION 

The nice system call adds the value of incr to the nice value of the calling 
process. A process's nice value is a non-negative number for which a more 
positive value results in lower CPU priority. 

A maximum nice value of 39 and a minimum nice value of are imposed by 
the system. (The default nice value is 20.) Requests for values above or 

limiT ""^^"^^ ^^^^ ^^^"^ ^^^"^^ *° corresponding 

[EPERM] The nice system call will fail and not change the nice value 

if incr is negative or greater than 39, and the effective user 
ID of the calling process is not super-user. 

SEE ALSO 

exec(2). 

nice(l) in the User's/System Administrator's Reference Manual. 
DIAGNOSTICS 

Upon successful completion, nice returns the new nice value minus 20 
Otherwise, a value of -1 is returned, and ermo is set to indicate the error. 
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NAME 

open - open for reading or writing 

SYNOPSIS 

#include <fcntLh> 

int open (path, oflag [, mode] ) 

char *path; 

int oflag, mode; 

DESCRIPTION 

Path points to a path name naming a file. The open system call opens a file 
descriptor for the named file and sets the file stahis flags according to the 
value of oflag. For non-STREAMS [see intro{2)] files, oflag values are con- 
structed by OR-ing flags from the following list (only one of the first three 
flags below may be used): 
0_RDONLY Open for reading only. 
0_WRONLY Open for writing only. 
O^RDWR Open for reading and writing. 

OJSrDELAY This flag may affect subsequent reads and writes [see read{2) 
and write (2)]. 

When opening a HFO with 0_RDONLY or 0_WRONLY set: 
If 0_NDELAY is set: 

An open for reading-only will return without delay. 
An open for writing-only will return an error if no 
process currenfly has the file open for reading. 

If 0_NDELAY is clear: 

An open for reading-only will block until a process 
opens the file for writing. An open for writing-only 
will block until a process opens the file for reading. 

When opening a file associated with a communication line: 
If 0_NDELAY is set: 

The open will return without waiting for carrier. 
If 0_NDELAY is clear: 

The open will block until carrier is present. 

O-APPEND If set, the file pointer will be set to the end of the file prior 
to each write. 

0_SYNC When opening a regular file, this flag affects subsequent 

writes. If set, each write (2) will wait for both the file data 
and file status to be physically updated. 
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0_TRUNC 



0_EXCL 



0_CREAT If the file exists, this flag has no effect. Otherwise, the 
owner ID of the file is set to the effective user ID of the pro- 
cess; the group ID of the file is set to the effective group ID 
of the process; and the low-order 12 bits of the file mode 
are set to the value of mode, modified as follows [see 
creat(2)]: ^ 

All bits set in the file mode creation mask of the 
process are cleared [see umask(2)]. 

The "save text image after execution bit" of the 
mode is cleared [see chmod{2)]. 

If the file exists, its length is truncated to and the mode 
and owner are unchanged. 

If 0__EXCL and 0_CREAT are set, open will fail if the file 
exists. 

When opening a STREAMS file, oflag may be constructed from 0_NDELAY 
or-ed with either 0_RDONLY, O.WRONLY or 0_RDWR. Other flag values 
are not applicable to STREAMS devices and have no effect on them The 
value of 0_NDELAY affects the operation of STREAMS drivers and certain 
system calls [see read(2l getmsg{2l VUtmsg{2), and u;nfe(2)]. For drivers the 
implementation of 0_NDELAY is device-specific. Each STREAMS device 
driver may treat this option differentiy. 

Certain flag values can be set follovdng open as described in fcntl{2). 

The file pointer used to mark the current position within the file is set to the 
beginning of the file. 

J^^/z'otr ^^s^riptor is set to remain open across exec system calls [see 

The named file is opened unless one or more of the following is true: 
[EACCES] A component of the path prefix denies search permission. 

[EACCES] oflag permission is denied for the named file. 

[EAGAIN] The file exists, mandatory file/record locking is set, and 

there are outstanding record locks on the file [see chmod 

[EEXIST] 0_CREAT and 0_EXCL are set, and the named file exists. 

[EFAULT] Path points outside the allocated address space of the pro- 

cess. ^ 

[EINTR] A signal was caught during the open system call. 

[EIO] A hangup or error occurred during a STREAMS open, 

[EISDIR] The named file is a directory and oflag is write or 

read/wiite. 

[EMFILE] NOHLES file descriptors are currentiy open. 
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Components of path require hopping to multiple remote 
machines. 

The system file table is full. 

O-CREAT is not set and the named file does not exist. 
Path points to a remote machine, and the link to that 
machine is no longer active. 

The system is unable to allocate a send descriptor. 
O-CREAT and 0_EXCL are set, and the file system is out of 
inodes. 

Unable to allocate a stream, 

A component of the path prefix is not a directory. 
The named file is a character special or block special file, 
and the device associated with this special file does not 
exist. 

0_NDELAY is set, the named file is a FIFO, 0_WRONLY is 
set, and no process has the file open for reading. 
A STREAMS module or driver open routine failed. 
The named file resides on a read-only file system and oflag 
is write or read/vmte. 

The file is a pure procedure (shared text) file that is being 
executed and oflag is write or read/write. 

SEE ALSO 

chmod(2), close(2), creat(2), dup(2), fcntl(2), intro(2), lseek(2), read(2), 
getmsg(2), putmsg(2), umask(2), write(2). 

DIAGNOSTICS 

Upon successful completion, the file descriptor is returned. Otherwise, a 
value of -1 is returned, and ermo is set to indicate the error. 



[EMULTIHOP] 

[ENFILE] 

[ENOENT] 

[ENOLINK] 

[ENOMEM] 
[ENOSPC] 

[ENOSR] 

[ENOTDIR] 

[ENXIO] 



[ENXIO] 

[ENXIO] 
[EROFS] 

[ETXTBSY] 
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NAME 

pause - suspend process until signal 

SYNOPSIS 

pause 

DESCRIPTION 

The pause system call suspends the calling process until it receives a signal. 
The signal must be one that is not currently set to be ignored by the calling 
process. ^ 

If the signal causes termination of the calling process, pause will not return. 
If the signal is caught by the calling process, and control is returned from 
the signal-catching function [see signal{2)l the calling process resumes exe- 
cution from the point of suspension; with a return value of -1 from pause 
and ermo set to EINTR. 

SEE ALSO 

alarm(2), kill(2), signal(2), sigpause(2), wait(2). 
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NAME 

pipe - create ar\ interprocess char\nel 

SYNOPSIS 

int pipe (fildes) 
int fildes[2]; 

DESCRIPTION 

The pipe system call creates an I/O mechanism called a pipe and returns 
two file descriptors, fildes[0] and fildes[l]. Fildes[0] is opened for reading 
and fildes[l] is opened for writing. 

Up to 5120 bytes of data are buffered by the pipe before the writing process 
is blocked. A read-only file descriptor fildes[0] accesses the data written to 
fildes[l] on a first-in-first-out (FIFO) basis. 

The pipe system call will fail if: 

[EMFILE] NOFILES file descriptors are currently open. 

[ENFILE] The system file table is full. 

SEE ALSO 

read(2), write(2). 

sh(l) in the User's /System Administrators Reference Manual 
DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and ermo is set to indicate the error. 
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NAME 

plock - lock process, text, or data in memory 
SYNOPSIS 

#include <sys/lock.h> 

int plock (op) 
int op; 

DESCRIPTION 

The plock system call allows the calling process to lock its text segment (text 
lock), its data segment (data lock), or both its text and data segments (pro- 
cess lock) into memory. Locked segments are immune to all routine swap- 
ping, plock also allows these segments to be unlocked. The effective user 
ID of the calling process must be super-user to use this call. Op specifies 
the following: 



PROCLOCK - 

TXTLOCK - 
DATLOCK - 
UNLOCK - 



lock text and data segments into memory (process 
lock) 

lock text segment into memory (text lock) 
lock data segment into memory (data lock) 
remove locks 



The plock system call will fail and not perform the requested operation if 
one or more of the following is true: 

[EPERM] The effective user ID of the calling process is not super- 

user. 

[EINVAL] Op is equal to PROCLOCK and a process lock, a text lock, 

or a data lock already exists on the calling process. 

[EINVAL] Op is equal to TXTLOCK and a text lock or a process lock 

already exists on the calling process. 

[EINVAL] Op is equal to DATLOCK and a data lock or a process lock 

already exists on the calling process. 

[EINVAL] Op is equal to UNLOCK and no type of lock exists on the 

calling process. 

[EAGAIN] Not enough memory. 

SEE ALSO 

exec(2), exit(2), fork(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned to the calling process. 
Otherwise, a value of -1 is returned, and ermo is set to indicate the error. 
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NAME 

poll - STREAMS input/output multiplexing 

SYNOPSIS 

#iiiclude <stropts.h> 
#include <poll.h> 

int polKfds, nfds, timeout) 
struct poUfd fds[]; 
unsigned long nfds; 
int timeout; 

DESCRIPTION 

The poll system call provides users with a mechanism for multiplexing 
input/output over a set of file descriptors that reference open streams [see 
intro{2)]. The poll system call identifies those streams on which a user can 
send or receive messages, or on which certain events have occurred. A user 
can receive messages using read{2) or getmsg(2) and can send messages 
using write(2) and putmsg{2). Certain ioctl{2) calls, such as I_RECVFD and 
LSENDFD [see streamio{7)], can also be used to receive and send messages. 

Fds specifies the file descriptors to be examined and the events of interest 
for each file descriptor. It is a pointer to an array with one element for each 
open file descriptor of interest. The array's elements are pollfd structures 
which contain the following members: 

int fd; /* file descriptor */ 

short events; /* requested events */ 

short revents; /* returned events */ 

where fd specifies an open file descriptor and events and revents are bit- 
masks constructed by or-ing any combination of the following event flags: 

POLLIN A non-priority or file descriptor passing message (see 
L_RECVFD) is present on the stream head read queue. This flag 
is set even if the message is of zero length. In revents, this 
flag is mutually exclusive with POLLPRI. 

POLLPRI A priority message is present on the stream head read queue. 

This flag is set even if the message is of zero length. In 
revents, this flag is mutually exclusive with POLLIN. 

POLLOUT The first downstream write queue in the stream is not full. 

Priority control messages can be sent (see putmsg) at any time. 

POLLERR An error message has arrived at the stream head. This flag is 
only valid in the revents bitmask; it is not used in the events 
field. 

POLLHUP A hangup has occurred on the stream. This event and POLL- 
OUT are mutually exclusive; a stream can never be writable if a 
hangup has occurred. However, this event and POLLIN or 
POLLPRI are not mutually exclusive. This flag is only valid in 
the revents bitmask; it is not used in the events field. 
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POLLNVAL The specified fd value does not belong to an open stream. This 
flag is only valid in the revents field; it is not used in the 
events field. 

For each element of the array pointed to by fds, poll examines the given file 
descriptor for the event(s) specified in events. The number of file descrip- 
tors to be examined is specified by nfds. If nfds exceeds NOFILES, the sys- 
tem limit of open files [see ulimit{2)l poll will fail. 

If the value fd is less than zero, events is ignored and revents is set to in 
that entry on return from poll. 

The results of the poll query are stored in the revents field in the pollfd 
structure. Bits are set in the revents bitmask to indicate which of the 
requested events are true. If none are true, none of the specified bits is set 
in revents when the poll call returns. The event flags POLLHUP, POLLERR, 
and POLLNVAL are always set in revents if the conditions they indicate are 
true; this occurs even though these flags were not present in events. 

If none of the defined events have occurred on any selected file descriptor, 
poll waits at least timeout msec for an event to occur on any of the selected 
file descriptors. On a computer where millisecond timing accuracy is not 
available, timeout is rounded up to the nearest legal value available on that 
system. If the value timeout is 0, poll returns immediately. If the value of 
timeout is -1, poll blocks until a requested event occurs or until the call is 
interrupted. The poll system call is not affected by the 0_NDELAY flag. 
The poll system call fails if one or more of the following is true: 

[EAGAIN] Allocation of internal data structures failed but request should 
be attempted again. 

[EFAULT] Some argument points outside the allocated address space. 

[EINTR] A signal was caught during the poll system call. 

[EINVAL] The argument nfds is less than zero, or nfds is greater than 
NOFILES. 

SEE ALSO 

getmsg(2), intro(2), putmsg(2), read(2), write(2). 
streamio(7) in the User's/System Administrator's Reference Manual. 
STREAMS Primer. 
STREAMS Programmer's Guide. 
DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. A positive 
value indicates the total number of file descriptors that has been selected 
(i.e., file descriptors for which the revents field is non-zero). A value of 
indicates that the call timed out and no file descriptors have been selected. 
Upon failure, a value of -1 is returned, and ermo is set to indicate the error. 
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NAME 

profil - execution time profile 
SYNOPSIS 

void profil (buff, bufsiz, offset, scale) 

void (* offset) 0; 

char *buff; 

int bufsiz, scale; 

DESCRIPTION 

Buff points to an area of core whose length (in bytes) is given by bufsiz. 
After this call, the user's program counter (pc) is examined each clock tick. 
Then the value of offset is subtracted from it, and the remainder multiplied 
by scale. If the resulting number corresponds to an entry inside buff, that 
entry is incremented. An entry is defined as a series of bytes with length 
sizeof(short). 

The scale is interpreted as an unsigned, fixed-point fraction with binary 
point at the left: 0177777 (octal) gives a 1-1 mapping of pc's to entries in 
buff; 077777 (octal) maps each pair of instruction entries together. 02(octal) 
maps all instructions onto the beginning of buff (producing a non- 
interrupting core clock). 

Profiling is turned off by giving a scale of or 1. It is rendered ineffective 
by giving a bufsiz of 0. Profiling is turned off when an exec is executed, but 
remains on in child and parent both after a fork. Profiling will be turned off 
if an update in buff would cause a memory fault. 

SEE ALSO 

prof(l), times(2), monitor(3C). 

DIAGNOSTICS 

Not defined. 
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NAME 

ptrace - process trace 

SYNOPSIS 

int ptrace (request, pid, addr, data); 
int request, pid, data; 

DESCRIPTION 

The ptrace system call provides a means by which a parent process may 
control the execution of a child process. Its primary use is for the imple- 
mentation of breakpoint debugging [see sdb{l)]. The child process behaves 
normally until it encounters a signal [see signal{2) for the list], at which time 
it enters a stopped state and its parent is notified via wait (2). When the 
child is in the stopped state, its parent can examine and modify its "core 
inriage" using ptrace. Also, the parent can cause the child either to ter- 
minate or continue, with the possibility of ignoring the signal that caused it 
to stop. The data type of the argument addr depends upon the particular 
request given to ptrace. 

The request argument determines the precise action to be taken by ptrace 
and is one of the following: 

This request must be issued by the child process if it is to be 
traced by its parent. It turns on the child's trace flag that 
stipulates that the child should be left in a stopped state upon 
receipt of a signal rather than the state specified by func [see 
signal{2)]. The pid, addr, and data arguments are ignored, and 
a return value is not defined for this request. Peculiar results 
will ensue if the parent does not expect to trace the child. 

The remainder of the requests can only be used by the parent process. For 
each, pid is the process ID of the child. The child must be in a stopped state 
before these requests are made. 

1, 2 With these requests, the word at location addr in the address 
space of the child is returned to the parent process. If I and D 
space are separated, request 1 returns a word from I space, and 
request 2 returns a word from D space. If I and D space are 
not separated, either request 1 or request 2 may be used with 
equal results. The data argument is ignored. 

3 With this request, the word at location addr in the child's USER 
area in the system's address space (see <sys/user.h>) is 
returned to the parent process. The data argument is ignored. 
This request will fail if addr is outside the USER area, in which 
case a value of -1 is returned to the parent process and the 
parent's ermo is set to EIO. 

4, 5 With these requests, the value given by the data argument is 
written into the address space of the child at location addr. If 
I and D space are separated, request 4 writes a word into I 
space, and request 5 writes a word into D space. If I and D 
space are not separated, either request 4 or request 5 may be 
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used with equal results. Upon successful completion, the 
value written into the address space of the child is returned to 
the parent. These two requests will fail if addr is a location in 
a pure procedure space and another process is executing in 
that space. Upon failure a value of -1 is returned to the 
parent process and the parent's ermo is set to EIO. 

With this request, a few entries in the child's USER area can be 
written. Data gives the value that is to be written and addr is 
the location of the entry. The few entries that can be written 
are all registers. 

On the 80386, the ptrace system call can be used to modify 
the debug registers. 

The 80386 debug registers are used to specify an address to 
monitor in a user process. Any access to this location by the 
user process will deliver a SIGTRAP [see signal(2)] to the user 
process and possibly restart the parent process. 

The 80386 debug registers can be accessed by using the 3 or 6 
options of the ptrace system call to read or write a traced- 
process's u-area. The file <sys/debugreg.h> should be 
included in the parent process that wants to control the debug 
registers. This header file defines bit masks that describe the 
debug-registers in the u__debugreg[] array in the u-area. 

The debug registers numbered u.U->debugreg[DR_FIRSTADDR] 
(%drO) to u.u_-debugreg[DR_LASTADDR] (%dr3) contain pro- 
cess addresses which will be monitored according to the 
instructions provided in u.u_debugreg[DR_CONTROL] (%dr7). 
Only the DR__LOCAL_ENABLE_MASK and the various 
read/write and length bits in u.u-_debugreg[DR_CONTROL] can 
be set. Setting DR_LOCAL_SLOWDOWN to slow down pro- 
cessing is also highly recommended. The setting of all other 
bits is undefined and should be set to zero to ensure compati- 
bility with future Intel processors. 

In the process being debugged, these registers are automati- 
cally loaded before entering user-mode (privilege level 3) and 
cleared before entering the system for any reason. In UNIX 
System V Release 3.0, if the location specified by a debug- 
register is accessed during a system call, core-dump, or inter- 
rupt service, no trap will ensue. 
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7 This request causes the child to resume execution. If the data 
argument is 0, all pending signals including the one that 
caused the child to stop are canceled before it resumes execu- 
tion. If the data argument is a valid signal number, the child 
resumes execution as if it had incurred that signal, and any 
other pending signals are canceled. The addr argument must 
be equal to 1 for this request. Upon successful completion, the 
value of data is returned to the parent. This request will fail if 
data is not or a valid signal number, in which case a value 
of -1 is returned to the parent process and the parent's errno 
is set to EIO. 

8 This request causes the child to terminate with the same 
consequences as exit (2). 

9 This request sets the trace bit in the Processor Status Word of 
the child and then executes the same steps as listed above for 
request 7. The trace bit causes an interrupt upon completion 
of one machine instruction. This effectively allows single step- 
ping of the child. 

To forestall possible fraud, ptrace inhibits the set-user-ID facility on subse- 
quent exec(2) calls. If a traced process calls exec, it will stop before execut- 
ing the first instruction of the new image showing signal SIGTRAP. 
General Errors 

The ptrace system call will in general fail if the child process is running 
under i286emul{l) or one or more of the following is true: 

[EIO] Request is an illegal number, 

[ESRCH] Pid identifies a child that does not exist or has not executed 

a ptrace with request 0. 

SEE ALSO 

sdb(l), exec(2), signal(2), wait(2). 
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NAME 

putmsg - send a message on a stream 

SYNOPSIS 

#include <stropts.h> 

int putmsg (fd, ctlptr, dataptr, flags) 
int fd; 

struct strbuf *ctlptr; 
struct strbuf *dataptr; 
int flags; 

DESCRIPTION 

The putmsg system call creates a message [see intro{2)] from user specified 
buffer(s) and sends the message to a STREAMS file. The message may con- 
tain either a data part, a control part or both. The data and control parts to 
be sent are distinguished by placement in separate buffers, as described 
below. The semantics of each part is defined by the STREAMS module that 
receives the message. 

fd specifies a file descriptor referencing an open stream, ctlptr and dataptr 
each point to a strbuf structure which contains the following members: 

int maxlen; /* not used */ 

int len; /* length of data */ 

char*buf; /* ptr to buffer */ 

ctlptr points to the structure describing the control part, if any, to be 
included in the message. The buf field in the strbuf structure points to the 
buffer where the control information resides, and the len field indicates the 
number of bytes to be sent. The maxlen field is not used in putmsg [see 
getmsg{2)y In a similar manner, dataptr specifies the data, if any, to be 
included in the message, flags may be set to the values or RS_HIPRI and 
is used as described below. 

To send the data part of a message, dataptr must be non-NULL and the len 
field of dataptr must have a value of or greater. To send the control part 
of a message, the corresponding values must be set for ctlptr. No data (con- 
trol) part will be sent if either dataptr (ctlptr) is NULL or the len field of 
dataptr (ctlptr) is set to -1. 

If a control part is specified, and flags is set to RS_H1PRI, a priority message 
is sent. If flags is set to 0, a non-priority message is sent. If no control part 
is specified, and flags is set to RS_HIPRI, putmsg fails and sets errno to EIN- 
VAL. If no control part and no data part are specified, and flags is set to 0, 
no message is sent, and is returned. 

For non-priority messages, putmsg will block if the stream write queue is full 
due to internal flow control conditions. For priority messages, putmsg does 
not block on this condition. For non-priority messages, putmsg does not 
block when the write queue is full and 0_NDELAY is set. Instead, it fails 
and sets errno to EAGAIN. 
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The putmsg system call also blocks, unless prevented by lack of internal 
resources, waiting for the availability of message blocks in the stream, 
regardless of priority or whether 0-_NDELAY has been specified. No partial 
message is sent. 

The putmsg system call fails if one or more of the following is true: 

[EAGAIN] A non-priority message was specified, the O-NDELAY flag is 
set, and the stream write queue is full due to internal flow 
control conditions. 

[EAGAIN] Buffers could not be allocated for the message that was to be 
created. 

[EBADF] fd is not a valid file descriptor open for writing. 

[EFAULT] ctlptr or dataptr points outside the allocated address space. 

[EINTR] A signal was caught during the putmsg system call. 

[EINVAL] An undefined value was specified in flags, or flags is set to 
RS_HIPRI and no control part was supplied. 

[EINVAL] The stream referenced by fd is linked below a multiplexer. 

[ENOSTR] A stream is not associated with fd, 

[ENXIO] A hangup condition was generated downstream for the speci- 

fied stream, 

[ERANGE] The size of the data part of the message does not fall within 
the range specified by the maximum and minimum packet 
sizes of the topmost stream module. This value is also 
returned if the control part of the message is larger than the 
maximum configured size of the control part of a message, or 
if the data part of a message is larger than the maximum con- 
figured size of the data part of a message. 

A putmsg also fails if a STREAMS error message had been processed by the 
stream head before the call to putmsg. The error returned is the value con- 
tained in the STREAMS error message. 

SEE ALSO 

intro(2), read(2), getmsg(2), poll(2), write(2). 

STREAMS Primer, 

STREAMS Programmer's Guide, 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and ermo is set to indicate the error. 
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NAME 

read - read from file 

SYNOPSIS 

int read (fildes, buf, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat{T), open{l), dup{2), fcntl{2), 
or pipe (2) system call. 

The read system call attempts to read nbyte bytes from the file associated 
with fildes into the buffer pointed to by buf. 

On devices capable of seeking, the read starts at a position in the file given 
by the file pointer associated with fildes. Upon return from read, the file 
pointer is incremented by the number of bytes actually read. 

Devices that are incapable of seeking always read from the current position. 
The value of a file pointer associated with such a file is undefined. 

Upon successful completion, read returns the number of bytes actually read 
and placed in the buffer; this number may be less than nbyte if the file is 
associated with a communication line [see ioctl{2) and termio{7)], or if the 
number of bytes left in the file is less than nbyte bytes. A value of is 
returned when an end-of-file has been reached. 

A read from a STREAMS [see intro{2)] file can operate in three different 
modes: "byte-stream" mode, "message-nondiscard" mode, and "message- 
discard" mode. The default is byte-stream mode. This can be changed 
using the L-SRDOPT ioctl request [see streamio{7)], and can be tested with 
the L-GRDOPT ioctl. In byte-stream mode, read will retrieve data from the 
stream until it has retrieved nbyte bytes, or until there is no more data to be 
retrieved. Byte-stream mode ignores message boundaries. 

In STREAMS message-nondiscard mode, read retrieves data until it has read 
nbyte bytes, or until it reaches a message boundary. If the read does not 
retrieve all the data in a message, the remaining data are replaced on the 
stream, and can be retrieved by the next read or getmsg{2) call. Message- 
discard mode also retrieves data until it has retrieved nbyte bytes, or it 
reaches a message boundary. However, unread data remaining in a mes- 
sage after the read returns are discarded and are not available for a subse- 
quent read or getmsg. 

When attempting to read from a regular file with mandatory file/record 
locking set [see chmod{2)], and there is a blocking (i.e., owned by another 
process) write lock on the segment of the file to be read: 

If 0_NDELAY is set, the read will return a -1 and set ermo to 
EAGAIN. 

If 0_NDELAY is clear, the read v^l sleep until the blocking record 
lock is removed. 
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When attempting to read from an empty pipe (or FIFO): 
If 0_NDELAY is set, the read will return a 0. 

If O-NDELAY is clear, the read will block until data is written to the 
file or the file is no longer open for writing. 

When attempting to read a file associated with a tty that has no data 
currently available: 

If 0_NDELAY is set, the read will return a 0, 

If 0_NDELAY is clear, the read will block until data becomes avail- 
able. 

When attempting to read a file associated with a stream that has no data 
currently available: 

If 0_NDELAY is set, the read will return a -1 and set errno to 
EAGAIN. 

If 0_NDELAY is clear, the read will block until data becomes avail- 
able. 

When reading from a STREAMS file, handling of zero-byte messages is deter- 
mined by the current read mode setting. In byte-stream mode, read accepts 
data until it has read nbyte bytes, or until there is no more data to read, or 
until a zero-byte message block is encountered. The read system call then 
returns the number of bytes read, and places the zero-byte message back on 
the stream to be retrieved by the next read or getmsg. In the two other 
modes, a zero-byte message returns a value of and the message is 
removed from the stream. When a zero-byte message is read as the first 
message on a stream, a value of is returned regardless of the read mode. 

A read from a STREAMS file can only process data messages. It cannot pro- 
cess any type of protocol message and will fail if a protocol message is 
encountered at the stream head. 

The read system call will fail if one or more of the following are true: 

[EAGAIN] Mandatory file/record locking was set, 0_NDELAY was 

set, and there was a blocking record lock. 

[EAGAIN] Total amount of system memory available when reading 

via raw lO is temporarily insufficient. 

[EAGAIN] No message waiting to be read on a stream and 0_NDELAY 

flag set. 

[EBADF] Fildes is not a valid file descriptor open for reading. 

[EBADMSG] Message waiting to be read on a stream is not a data mes- 
sage. 

[EDEADLK] The read was going to go to sleep and cause a deadlock 
situation to occur. 

[EFAULT] Buf points outside the allocated address space. 

[EINTR] A signal was caught during the read system call. 



-2- 



READ(2) 



(C Software Development Set) 



READ(2) 



[EIO] A physical I/O error has occurred. 

[ENXIO] The device associated with the file-descriptor is a block- 

special or character-special file, and the value of the file- 
pointer is out of range. 

[EINVAL] Attempted to read from a stream linked to a multiplexer. 

[ENOLCK] The system record lock table was full, so the read could not 

go to sleep until the blocking record lock was removed. 

[ENOLINK] Fildes is on a remote machine and the link to that machine 
is no longer active. 

A read from a STREAMS file will also fail if an error message is received at 
the stream head. In this case, errno is set to the value returned in the error 
message. If a hangup occurs on the stream being read, read will continue to 
operate normally until the stream head read queue is empty. Thereafter, it 
will return 0. 

SEE ALSO 

creat(2), dup{2), fcntl(2), ioctl(2),intro(2), open(2), pipe(2), getmsg(2). 
streamio(7), termio(7) in the User's /System Administrator's Reference Manual. 

DIAGNOSTICS 

Upon successful completion a non-negative integer is returned indicating 
the number of bytes actually read. Otherv^se, a -1 is returned, and errno is 
set to indicate the error. 
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NAME 

rmdir - remove a directory 

SYNOPSIS 

int rmdir (path) 
char 4path; 

DESCRIPTION 

rmdir removes the directory named by the path name pointed to by path. 
The directory must not have any entries other than "." and 

The named directory is removed unless one or more of the following is true: 

[EINVAL] The current directory may not be removed. 

[EINVAL] The " . " entry of a directory may not be removed. 

[EEXIST] The directory contains entries other than those for " . " and 

II It 

[ENOTDIR] A component of the path prefbc is not a directory. 
[ENOENT] The named directory does not exist. 

[EACCES] Search permission is denied for a component of the path 

prefix. 

[EACCES] Write permission is denied on the directory containing the 

directory to be removed. 

[EBUSY] The directory to be removed is the mount point for a 

mounted file system. 

[EROFS] The directory entry to be removed is part of a read-only file 

system. 

[EFAULT] Path points outside the process's allocated address space. 

[EIO] An I/O error occurred while accessing the file system. 

[ENOLINK] Path points to a remote machine, and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

In addition, a directory will not be removed when all of the following is 
true: 

the parent directory has the sticky bit set 
the parent directory is not owned by the user 
the directory is not owned by the user 
the directory is not writable by the user 
the user is not super-user 
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SEE ALSO 

mkdir(2). 

nndir(l), nn(l), and mkdir(l) in the User's/System Administrator's Reference 
Manual. 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and ermo is set to indicate the error. 
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NAME 

semctl - semaphore control operations 

SYNOPSIS 

#include <sys/types.h> 
#include <sy8/ipc.h> 
#include <sy8/8em.h> 

int semctl (semid, semnum, cmd, arg) 
int semid, cmd; 
int semnum; 
union semun { 
int val; 

struct semid_ds «buf; 
ushort *array; 
} arg; 

DESCRIPTION 

The semctl system call provides a variety of semaphore control operations as 
specified by cmd. 

The following cmds are executed with respect to the semaphore specified by 
semid and semnum : 



GETVAL Return the value of semval [see intro{2)l {READ} 

SETVAL Set the value of semval to arg.val, {ALTER} When 
this cmd is successfully executed, the semadj value 
corresponding to the specified semaphore in all 
processes is cleared. 

GETPID Return the value of sempid. {READ} 

GETNCNT Return the value of semncnt. {READ} 

GETZCNT Return the value of semzcnt. {READ} 

The following cmds return and set, respectively, every semval in the set of 
semaphores. 



GETALL 



SET ALL 



Place semvals into array pointed to by arg. array. 
{READ} 

Set semvals according to the array pointed to by 
arg.array. {ALTER} When this cmd is successfully exe- 
cuted the semadj values corresponding to each speci- 
fied semaphore in all processes are cleared. 

The following cmds are also available: 

IPC_STAT Place the current value of each member of the data 
structure associated with semid into the structure 
pointed to by arg.buf. The contents of this structure 
are defined in intro{2). {READ} 
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IPC— SET Set the value of the following members of the data 
structure associated with semid to the corresponding 
value found in the structure pointed to by arg.buf: 

sem_perm.uid 
sem ^peri]i.gid 

seiiL-perm.mode /* only low 9 bits */ 

This cmdfl can only be executed by a process that has an 
effective user ID equal to either that of super-user, or to 
the value of sem_perm.cuid or sem-.perm.uid in the 
data structure associated with semid, 

IPC_RMID Remove the semaphore identifier specified by semid 
from the system and destroy the set of semaphores 
and data structure associated vydth it. This cmd can 
only be executed by a process that has an effective 
user ID equal to either that of super-user, or to the 
value of sem— perm.cuid or sem_perm.uid in the 
data structure associated with semid. 

The semctl system call fails if one or more of the following is true: 

[EINVAL] Semid is not a valid semaphore identifier. 

[EINVAL] Semnum is less than zero or greater than sem_nsems. 

[EINVAL] Cmd is not a valid command. 

[EACCES] Operation permission is denied to the calling process 
[see intro(2)]. 

[ERANGE] Cmd is SETVAL or SET ALL and the value to which 
semval is to be set is greater than the system imposed 
maximum. 

[EPERM] Cmd is equal to IPC_RMID or IPC_SET and the effec- 
tive user ID of the calling process is not equal to that 
of super-user or to the value of sem_perm.cuid or 
sem— perm.uid in the data structure associated with 
semid. 

[EFAULT] Arg.buf points to an illegal address. 

SEE ALSO 

intro(2), semget(2), semop(2). 

DL\GNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 

GETVAL The value of semval. 

GETPID The value of sempid. 

GETNCNT The value of semncnt. 

GETZCNT The value of semzcnt. 

All others A value of 0. 

Otherwise, a value of -1 is returned, and ermo is set to indicate the error. 
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NAME 

semget - get set of semaphores 

SYNOPSIS 

#include <sys/type8.h> 
#mclude <sy8/ipc.h> 
#include <sys/sein.h> 

int semget (key, nsems, semflg) 

key_t key; 

int nsems, semflg; 

DESCRIPTION 

The semget system call returns the semaphore identifier associated with key. 

A semaphore identifier and associated data structure and set containing 
nsems semaphores [see intro{2)] are created for key if one of the following is 
true: 

Key is equal to IPC_PRIVATE. 

Key does not already have a semaphore identifier associated with it, 
and (semflg & IPC_CREAT) is "true". 

Upon creation, the data structure associated with the new semaphore iden- 
tifier is initialized as follows: 

Sem_perm.cuid, sem_perm.uid, sem— .perm.cgid, and 
sem_perm.gid are set equal to the effective user ID and effective 
group ID, respectively, of the calling process. 

The low-order 9 bits of sem. perm.mode are set equal to the low- 
order 9 bits of semflg, 

Sem—nsems is set equal to the value of nsems. 

Sem_otime is set equal to and semL_ctime is set equal to the 
current time. 

The data structure associated with each semaphore in the set is not initial- 
ized. The function semctl with the command setval or setall can be used to 
initialize each semaphore. 

The semget system call fails if one or more of the following is true: 

[EINVAL] Nsems is either less than or equal to zero or greater than 

the system-imposed limit. 

[EACCES] A semaphore identifier exists for key, but operation permis- 

sion [see intro{l)] as specified by the low-order 9 bits of 
semflg would not be granted. 

[EINVAL] A semaphore identifier exists for key, but the number of 

semaphores in the set associated with it is less than nsems, 
and nsems is not equal to zero. 

[ENOENT] A semaphore identifier does not exist for key, and (semflg & 

IPC_CREAT) is "false". 
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[ENOSPC] A semaphore identifier is to be created, but the system- 

imposed limit on the maximum number of allowed sema- 
phore identifiers system wide would be exceeded. 

[ENOSPC] A semaphore identifier is to be created, but the system- 

imposed limit on the maximum number of allowed sema- 
phores system wide would be exceeded. 

[EEXIST] A semaphore identifier exists for key, but [(semflg & 

IPC_CREAT) and {semflg & IPC_EXCL)] are "true". 

SEE ALSO 

intro(2), semctl(2), semop(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a semaphore 
identifier, is returned. Otherwise, a value of -1 is returned, and ermo is set 
to indicate the error. 
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NAME 

semop - semaphore operations 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/sem.h> 

int semop (semid, sops, nsops) 
int semid; 

struct sembuf 'i'^sops; 
unsigned nsops; 

DESCRIPTION 

The semop system call is used to automatically perform an array of sema- 
phore operations on the set of semaphores associated with the semaphore 
identifier specified by semid. Sops is a pointer to the array of semaphore- 
operation structures. Nsops is the number of such structures in the array. 
The contents of each structure includes the following members: 

short sem_num; /♦ semaphore number */ 
short sem_op; /* semaphore operation */ 
short sem_Jlg; /* operation flags */ 

Each semaphore operation specified by sem^op is performed on the 
corresponding semaphore specified by semid and sem^num. 

Sem—op specifies one of three semaphore operations as follows: 

If sem^op is a negative integer, one of the following will occur: 
{ALTER} 

If semval [see intro(l)\ is greater than or equal to the abso- 
lute value of sem^op, the absolute value of sem—op is sub- 
tracted from semval. Also, if {sem—flg & SEM_UNDO) is 
"true", the absolute value of sem^op is added to the calling 
process's semadj value [see exit(l)\ for the specified sema- 
phore. 

If semval is less than the absolute value of sem—op and 
(sem^flg & IPCJSroWAIT) is "true", semop will return 
immediately. 

If semval is less than the absolute value of sem^op and 
(sem^flg & IPCUSroWAIT) is "false", semop will increment 
the semncnt associated with the specified semaphore and 
suspend execution of the calling process until one of the 
following conditions occurs: 

Semval becomes greater than or equal to the absolute 
value of sem_op. When this occurs, the value of semncnt 
associated with the specified semaphore is decremented, 
the absolute value of sem^op is subtracted from semval 
and, if {sem-flg & SEM_UNDO) is "true", the absolute 
value of sem—op is added to the calling process's semadj 
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value for the specified semaphore. 

The semid for which the calling process is awaiting action 
is removed from the system [see semctl{2)]. When this 
occurs, ermo is set equal to EIDRM, and a value of -1 is 
returned. 

The calling process receives a signal that is to be caught. 
When this occurs, the value of semncnt associated with 
the specified semaphore is decremented, and the calling 
process resumes execution in the manner prescribed in sig- 
nal(2). 

If sent— op is a positive integer, the value of sem^op is added to 
semval and, if (sent— fig & SEM_UNDO) is "true", the value of 
sem^op is subtracted from the calling process's semadj value for the 
specified semaphore. {ALTER} 

If sem-.op is zero, one of the following will occur: {READ} 

If semval is zero, semop will return immediately. 

If semval is not equal to zero and {sem—flg & 
IPC—NOWAIT) is "true", semop will return immediately. 

If semval is not equal to zero and {sem—flg & 
IPC—NOWAIT) is "false", semop will increment the semzcnt 
associated with the specified semaphore and suspend exe- 
cution of the calling process until one of the following 
occurs: 

Semval becomes zero, at which time the value of semzcnt 
associated with the specified semaphore is decremented. 

The semid for which the calling process is awaiting action 
is removed from the system. When this occurs, ermo is 
set equal to EIDRM, and a value of -1 is returned. 

The calling process receives a signal that is to be caught. 
When this occurs, the value of semzcnt associated with 
the specified semaphore is decremented, and the calling 
process resumes execution in the manner prescribed in sig- 
nal{2). 

The semop system call will fail if one or more of the following is true for 
any of the semaphore operations specified by sops: 

[EINVAL] Semid is not a valid semaphore identifier. 

[EFBIG] Sem—num is less than zero or greater than or equal to the 

number of semaphores in the set associated with semid. 

[E2BIG] Nsops is greater than the system-imposed maximum. 

[EACCES] Operation permission is denied to the calling process [see 

intro{2)]. 
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[EAGAIN] The operation would result in suspension of the calling 

process but (sem^flg & IPC_NOWAIT) is "true". 

[ENOSPC] The limit on the number of individual processes requesting 

an SEM_UNDO would be exceeded. 

[EINVAL] The number of individual semaphores for which the calling 

process requests an SEM_UNDO would exceed the limit. 

[ERANGE] An operation would cause a semval to overflow the 

system-imposed limit. 

[ERANGE] An operation would cause a semadj value to overflow the 

system-imposed limit. 

[EFAULT] Sops points to an illegal address. 

Upon successful completion, the value of sempid for each semaphore speci- 
fied in the array pointed to by sops is set equal to the process ID of the cal- 
ling process. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), semctl(2), semget(2). 
DIAGNOSTICS 

If semop returns due to the receipt of a signal, a value of -1 is returned to 
the calling process and errno is set to EINTR. If it returns due to the removal 
of a semid from the system, a value of -1 is returned and errno is set to 
EIDRM. 

Upon successful completion, a value of zero is returned. Otherwise, a value 
of -1 is returned and errno is set to indicate the error. 
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NAME 

setpgrp - set process group ID 

SYNOPSIS 

int setpgrp () 

DESCRIPTION 

The setpgrp system call sets the process group ID of the calling process to 
the process ID of the calling process and returns the new process group ID. 

SEE ALSO 

exec(2), fork(2), getpid(2), intro(2), kill(2), signal(2). 
DIAGNOSTICS 

The setpgrp system call returns the value of the new process group ID. 
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NAME 

setuid, setgid - set user and group IDs 

SYNOPSIS 

int setuid (uid) 
int uid; 

int setgid (gid) 
int gid; 

DESCRIPTION 

The setuid (setgid) system call is used to set the real user (group) ID ar\d 
effective user (group) ID of the calling process. 

If the effective user ID of the calling process is super-user, the real user 
(group) ID and effective user (group) ID are set to uid (gid). 

If the effective user ID of the calling process is not super-user, but its real 
user (group) ID is equal to uid (gid), the effective user (group) ID is set to 
uid (gid). 

If the effective user ID of the calling process is not super-user, but the saved 
set-user (group) ID from exec(2) is equal to uid (gid), the effective user 
(group) ID is set to uid (gid). 

The setuid (setgid) system call will fail if the real user (group) ID of the cal- 
ling process is not equal to uid (gid) and its effective user ID is not super- 
user. [EPERM] 

The uid (gid) is out of range. [EINVAL] 
SEE ALSO 

getuid(2), intro(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and errno is set to indicate the error. 
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NAME 

shmctl - shared memory cor\trol operatior\s 

SYNOPSIS 

#include <8ys/type8.h> 
#include <sys/ipc.h> 
#include <sys/shm.h> 

int shmctl (shmid, cmd, buf) 
int shmid, cmd; 
struct shmid_ds *bvLf; 

DESCRIPTION 

The shmctl system call provides a variety of shared memory control opera- 
tions as specified by cmd. The following cmds are available: 

IPC_STAT Place the current value of each member of the data structure 
associated with shmid into the structure pointed to by buf. 
The contents of this structure are defined in intro(2). {READ} 

IPC_SET Set the value of the following members of the data structure 
associated with shmid to the corresponding value found in the 
structure pointed to by buf: 



shm_perm.uid 
shm_perm.gid 

shm_perm.mode /* only low 9 bits */ 

This cmd can only be executed by a process that has an effec- 
tive user ID equal to that of super-user, or to the value of 
shm—perm.cuid or shm_perm.uid in the data structure asso- 
ciated with shmid. 

IPC-RMID Remove the shared memory identifier specified by shmid from 
the system and destroy the shared memory segment and data 
structure associated with it. This cmd can only be executed by 
a process that has an effective user ID equal to that of super- 
user, or to the value of shm— perm.cuid or shm_perm.uid in 
the data structure associated with shmid. 

SHNLLOCK Lock the shared memory segment specified by shmid in 
memory. This cmd can only be executed by a process that has 
an effective user ID equal to super-user. 

SHM_UNLOCK 

Unlock the shared memory segment specified by shmid. This 
cmd can only be executed by a process that has an effective 
user ID equal to super-user. 
The shmctl system call will fail if one or more of the following is true: 
[EINVAL] Shmid is not a valid shared memory identifier. 
[EINVAL] Cmd is not a valid command. 

[EACCES] Cmd is equal to IPC^TAT and {READ} operation permission is 
denied to the calling process [see intro(2)]. 
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[EPERM] Cmd is equal to IPCRMID or IPd-SET, and the effective user 
ID of the calling process is not equal to that of super-user or to 
the value of shm_perm.cuid or shm_perm.uid in the data 
structure associated with shmid. 

[EPERM] Cmd is equal to SHM_LOCK or SHMLUNLOCK, and the effec- 
tive user ID of the calling process is not equal to that of super- 
user. 

[EFAULT] Buf points to an illegal address. 

[ENOMEM] Cmd is equal to SHMJLOCK, and there is not enough memory. 
SEE ALSO 

shmget(2), shmop(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and ermo is set to indicate the error. 

NOTES 

The user must explicitly remove shared memory segments after the last 
reference to them has been removed. 
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NAME 

shmget - get shared memory segment identifier 

SYNOPSIS 

#mclude <sys/types.h> 

#include <8ys/ipc.h> 

#include <sys/shm.h> 

int shmget (key, size, shmflg) 

key—t key; 

int size, shmflg; 

DESCRIPTION 

The shmget system call returns the shared memory identifier associated with 
key, 

A shared memory identifier and associated data structure and shared 
memory segment of at least size bytes [see intro{2)] are created for key if one 
of the following is true: 

Key is equal to IPCJRIVATE. 

Key does not already have a shared memory identifier associated 

with it, and (shmflg & IPC_CREAT) is "true". 
Upon creation, the data structure associated with the new shared memory 
identifier is initialized as follows: 

ShmL_.perm.cuid, shm—perm.uid, shm— perm.cgid, and 

shm— perm.gid are set equal to the effective user ID and effective 

group ID, respectively, of the calling process. 

The low-order 9 bits of shm__perm.mode are set equal to the low- 
order 9 bits of shmflg. Shm-segsz is set equal to the value of size. 
Shm_Ipid, shm-nattch, shm-atime, and shm_-dtime are set 
equal to 0. 

ShmL-Ctime is set equal to the current time. 
The shmget system call will fail if one or more of the following is true: 
[EINVAL] Size is less than the system-imposed minimum or greater 

than the system-imposed maximum. 

[EACCES] A shared memory identifier exists for key, but operation 

permission [see intro{2)] as specified by the low-order 9 bits 
of shmflg would not be granted. 

[EINVAL] A shared memory identifier exists for key, but the size of 

the segment associated with it is less than size, and size is 
not equal to zero. 

[ENOENT] A shared memory identifier does not exist for key, and 

{shmflg & IPC-CREAT) is "false". 

[ENOSPC] A shared memory identifier is to be created, but the 

system-imposed limit on the maximum number of allowed 
shared memory identifiers system wide would be exceeded. 
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[ENOMEM] A shared memory identifier and associated shared memory 
segment are to be created, but the amount of available 
memory is not sufficient to fill the request. 

[EEXIST] A shared memory identifier exists for key but [{shmflg & 

IPC_CREAT) and (shmflgiz IPC_EXCL)] are "true". 

SEE ALSO 

intro(2), shmctl(2), shmop(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a shared 
memory identifier is returned. Otherwise, a value of -1 is returned, and 
ermo is set to indicate the error. 

NOTES 

The user must explicitly remove shared memory segments after the last 
reference to them has been removed. 
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NAME 

shmop: shmat, shmdt - shared memory operations 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 
#include <sys/shm.h> 

char «shmat (shmid, shmaddr, shmflg) 
int shmid; 
char ♦shmaddr; 
int shmflg; 

int shmdt (shmaddr) 
char *shmaddr; 

DESCRIPTION 

The shmat system call attaches the shared memory segment associated with 
the shared memory identifier specified by shmid to the data segment of the 
calling process. The segment is attached at the address specified by one of 
the following criteria: 

If shmaddr is equal to zero, the segment is attached at the first avail- 
able address as selected by the system. 

If shmaddr is not equal to zero and (shmflg & SHNLRND) is ''true", 
the segment is attached at the address given by (shmaddr - (shmaddr 
modulus SHMLBA)). 

If shmaddr is not equal to zero and (shmflg & SHM_RND) is "false", 
the segment is attached at the address given by shmaddr. 

Shmdt detaches from the calling process's data segment the shared memory 
segment located at the address specified by shmaddr. 

The segment is attached for reading if (shmflg & SHM_-RDONLY) is "true" 
{READ}; otherwise it is attached for reading and writing {READ/WRITE}. 

Shmat will fail and not attach the shared memory segment if one or more of 
the following is true: 

[EINVAL] Shmid is not a valid shared memory identifier. 

[EACCES] Operation permission is denied to the calling process [see 

intro(2)]. 

[ENOMEM] The available data space is not large enough to accommo- 
date the shared memory segment. 

[EINVAL] Shmaddr is not equal to zero, and the value of (shmaddr - 

(shmaddr modulus SHMLBA)) is an illegal address. 

[EINVAL] Shmaddr is not equal to zero, (shmflg & SHM_RND) is 

"false", and the value of shmaddr is an illegal address. 

[EMFILE] The number of shared memory segments attached to the 

calling process would exceed the system-imposed limit. 
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[EINVAL] Shmdt will fail and not detach the shared memory segment 

if shmaddr is not the data segment start address of a shared 
memory segment. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), shmctl(2), shmget(2). 
DIAGNOSTICS 

Upon successful completion, the return value is as follows: 

Shmai returns the data segment start address of the attached shared 
memory segment. 

Shmdt returns a value of 0. 

Otherwise, a value of -1 is returned, and ermo is set to indicate the error. 

NOTES 

The user must explicitly remove shared memory segments after the last 
reference to them has been removed. 
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NAME 

signal - specify what to do upon receipt of a signal 

SYNOPSIS 

#include <signal.h> 

void (^signal (sig, func))() 

int sig; 

void (*func)(); 

DESCRIPTION 

The signal system call allows the calling process to choose one of three 
ways in which it is possible to handle the receipt of a specific signal. Sig 
specifies the signal and func specifies the choice. 

Sig can be assigned any one of the following except SIGKILL: 

hangup 
interrupt 
quit 

illegal instruction (not reset when caught) 
trace trap (not reset when caught) 
lOT instruction 

used by abort, replaces SIGIOT 
EMT instruction 
floating point exception 
kill (cannot be caught or ignored) 
bus error 

segmentation violation 
bad argument to system call 
write on a pipe with no one to read it 
alarm clock 

software termination signal 
user-defined signal 1 
user-defined sienal 2 
death of a chila 
power fail 

selectable event pending 

Func is assigned one of three values: SIG_-DFL, SIG_IGN, or a function 
address, SIG_DFL, and SIG-JGN, are defined in the include file signal.h. 
Each is a macro that expands to a constant expression of type pointer to 
function returning void, and has a unique value that matches no declarable 
function. 

The actions prescribed by the values of func are as follows: 

SIG—DFL — terminate process upon receipt of a signal 

Upon receipt of the signal sig, the receiving process is to be ter- 
minated with all of the consequences ouSined in exit(2). See 
NOTE [1] below. 



SIGHUP 


01 


SIGINT 


02 


SIGQUIT 


031^1 


SIGILL 


04[i] 


SIGTRAP 


051^1 


SIGIOT 


061^1 


SIGABRT 


06 


SIGEMT 


07[ll 


SIGFPE 


08til 


SIGKILL 


09 


SIGBUS 


lOt^l 


SIGSEGV 


iiiu 


SIGSYS 


12m 


SIGPIPE 


13 


SIGALRM 


14 


SIGTERM 


15 


SIGUSRl 


16 


SIGUSR2 


17 


SIGCLD 


1812] 


SIGPWR 


19[2] 


SIGPOLL 


22^] 
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SIG_IGN — ignore sigr\al 

The signal sig is to be ignored. 

Note: the signal SIGKILL cannot be ignored. 

function address — catch signal 

Upon receipt of the signal sig, the receiving process is to execute 
the signal-catching function pointed to by func. The signal 
number sig will be passed as the only argument to the signal- 
catching function. Additional arguments are passed to the 
signal-catching function for hardware-generated signals. Before 
entering the signal-catching function, the value of func for the 
caught signal will be set to SIG_DFL unless the signal is SIGILL, 
SIGTRAP, or SIGPWR. 

Upon return from the signal-catching function, the receiving pro- 
cess will resume execution at the point it was interrupted. 

When a signal that is to be caught occurs during a read{l), a 
write {1), an open (2), or an ioctl{2) system call on a slow device 
(like a terminal; but not a file), during a pause (2) system call, or 
during a wait{2) system call that does not return immediately 
due to the existence of a previously stopped or zombie process, 
the signal catching function will be executed. Then the inter- 
rupted system call may return a -1 to the calling process with 
errno set to EINTR. 

The signal system call vydll not catch an invalid function argu- 
ment, func, and results are undefined when an attempt is made 
to execute the function at the bad address. 

Note: The signal SIGKILL cannot be caught. 

A call to signal cancels a pending signal sig except for a pending SIGKILL 
signal. 

The signal system call will fail if sig is an illegal signal number, including 
SIGKILL. [EINVAL] 

SEE ALSO 

intro(2), kill(2), pause(2), ptrace(2), wait(2), setjmp(3C), sigset(2). 
kill(l) in the User's/System Administrator's Reference Manual 

DIAGNOSTICS 

Upon successful completion, signal returns the previous value of func for 
the specified signal sig. Otherwise, a value of SIG_ERR is returned and 
errno is set to indicate the error, SIG_ERR is defined in the include file 
signal.h. 

NOTES 

[1] If SIG__DFL is assigned for these signals, in addition to the process being 
terminated, a "core image" will be constructed in the current working 
directory of the process, if the following conditions are met: 
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The effective user ID and the real user ID of the receiving pro- 
cess are equal. 

An ordinary file named core exists and is writable or can be 
created. If the file must be created, it will have the following 
properties: 

• a mode of 0666 modified by the file creation 
mask [see umask(2)] 

• a file owner ID that is the same as the effective 
user ID of the receiving process 

• a file group ID that is the same as the effective 
group ID of the receiving process. 

[2] For the signals SIGCLD and SIGPWR, func is assigned one of three 
values: SIG_-DFL, SIG_IGN, or a function address. The actions 
prescribed by these values are: 

SIG— DEL — ignore signal 

The signal is to be ignored. 

SIG_IGN — ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the cal- 
ling process's child processes will not create zombie 
processes when they terminate [see exit(2)]. 

function address — catch signal 

If the signal is SIGPWR, the action to be taken is the same as 
that described above for func equal to function address. The 
same is true if the signal is SIGCLD with one exception: 
while the process is executing the signal-catching function, 
any received SIGCLD signals will be ignored. (This is the 
default action.) 

In addition, SIGCLD affects the wait and exit system calls as follows: 

wait If the func value of SIGCLD is set to SIG_IGN and a wait is 
executed, the wait will block until all of the calling process's 
child processes terminate; it will then return a value of -1 
with ermo set to ECHILD. 

exit If in the exiting process's parent process the func value of 
SIGCLD is set to SIG_IGN, the exiting process will not create 
a zombie process. 

When processing a pipeline, the shell makes the last process in the 
pipeline the parent of the preceding processes. A process that may 
be piped into in this manner (and thus become the parent of other 
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processes) should take care not to set SIGCLD to be caught. 

[3] SIGPOLL is issued when a file descriptor corresponding to a STREAMS 
[see intro{2)] file has a "selectable" event pending. A process must 
specifically request that this signal be sent using the I_SETSIG ioctl call. 
Otherwise, the process will never receive SIGPOLL. 
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NAME 

sigset, sighold, sigrelse, sigignore, sigpause - signal management 

SYNOPSIS 

#include <signal.h> 

void (♦sigset (sig, func))() 

int sig; 

void (*func)(); 

int sighold (sig) 

int sig; 

int sigrelse (sig) 

int sig; 

int sigignore (sig) 

int sig; 

int sigpause (sig) 

int sig; 

DESCRIPTION 

These functions provide signal management for application processes. The 
sigset system call specifies the system signal action to be taken upon receipt 
of signal sig. This action is either calling a process signal-catching handler 
func or performing a system-defined action. 

Sig can be assigned any one of the following values except SIGKILL. 
Machine- or implementation-dependent signals are not included (see NOTES 
below). Each value of sig is a macro, defined in <signaLh>, that expands to 
an integer constant expression. 

SIGHUP hangup 

SIGINT interrupt 

SIGQUIT* quit 

SIGILL* illegal instruction (not held when caught) 

SIGTRAP* trace trap (not held when caught) 

SIGABRT* abort 

SIGFPE* floating point exception 

SIGKILL kill (cannot be caught or ignored) 

SIGSYS* bad argument to system call 

SIGPIPE write on a pipe with no one to read it 

SIGALRM alarm clock 

SIGTERM software termination signal 

SIGUSRl user-defined signal 1 

SIGUSR2 user-defined signal 2 

SIGCLD death of a child (see WARNING below) 

SIGPWR power fail (see WARNING below) 

SIGPOLL selectable event pending (see NOTES below) 

See below under SIG_DFL regarding asterisks (*) in the above list. 
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The following values for the system-defined actions of func are also defined 
in <signal.h>. Each is a macro that expands to a constant expression of 
type pointer to function returning void and has a unique value that matches 
no declarable function. 

SIG_DFL — default system action 

Upon receipt of the signal sig, the receiving process is to be ter- 
minated with all of the consequences outlined in exit{2). In 
addition a "core image" will be made in the current working 
directory of the receiving process if sig is one for which an aster- 
isk appears in the above list and the foUov^ng conditions are 
met: 

The effective user ID and the real user ID of the receiving 
process are equal. 

An ordinary file named core exists and is writable or can 
be created. If the file must be created, it will have the fol- 
lowing properties: 

a mode of 0666 modified by the file creation mask 
[see umask{2)] 

a file owner ID that is the same as the effective user 
ID of the receiving process 

a file group ID that is the same as the effective 
group ID of the receiving process. 



SIG-JGN — ignore signal 

Any pending signal sig is discarded and the system signal action is 
set to ignore future occurrences of this signal type. 

SIG-HOLD —hold signal 

The signal sig is to be held upon receipt. Any pending signal of 
this type remains held. Only one signal of each type is held. 

Otherwise, func must be a pointer to a function, the signal-catching handler, 
that is to be called when signal sig occurs. In this case, sigset specifies that 
the process will call this function upon receipt of signal sig. Any pending 
signal of this type is released. This handler address is retained across calls 
to the other signal management functions listed here. 

When a signal occurs, the signal number sig will be passed as the only 
argument to the signal-catching handler. Before calling the signal-catching 
handler, the system signal action will be set to SIG_HOLD. During normal 
return from the signal-catching handler, the system signal action is restored 
to func and any held signal of this type released. If a non-local goto 
(longjmp) is taken, then sigrelse must be called to restore the system signal 
action and release any held signal of this type. 
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In general, upon return from the signal-catching handler, the receiving pro- 
cess will resume execution at the point it was interrupted. However, when 
a signal is caught during a read{l), a write {1), an open(2), or an ioctl(2) sys- 
tem call during a sigpause system call, or during a wait (2) system call that 
does not return immediately due to the existence of a previously stopped or 
zombie process, the signal-catching handler will be executed. Then the 
interrupted system call may return a -1 to the calling process with errno set 
to EINTR. 

Sighold and sigrelse are used to establish critical regions of code. Sighold is 
analogous to raising the priority level and deferring or holding a signal until 
the priority is lowered by sigrelse, Sigrelse restores the system signal action 
to that specified previously by sigset, 

Sigignore sets the action for signal sig to SIG_IGN (see above). 

Sigpause suspends the calling process until it receives a signal, the same as 
pause (2), However, if the signal sig had been received and held, it is 
released and the system signal action taken. This system call is useful for 
testing variables that are changed on the occurrence of a signal. The correct 
usage is to use sighold to block the signal first, then test the variables. If 
they have not changed, then call sigpause to wait for the signal, sigset will 
fail if one or more of the following is true: 

[EINVAL] Sig is an illegal signal number (including SIGKILL) or the 

default handling of sig cannot be changed. 

[EINTR] A signal was caught during the system call sigpause . 

SEE ALSO 

kill(2), pause(2), signal(2), wait(2), setjmp(3C). 
DIAGNOSTICS 

Upon successful completion, sigset returns the previous value of the system 
signal action for the specified signal sig. Otherwise, a value of SIG_ERR is 
returned and ermo is set to indicate the error. SIG_ERR is defined in 
<signal.h> . 

For the other functions, upon successful completion, a value of is 
returned. Otherwise, a value of -1 is returned and errno is set to indicate 
the error. 

NOTES 

SIGPOLL is issued when a file descriptor corresponding to a STREAMS [see 
intro(2)] file has a "selectable" event pending. A process must specifically 
request that this signal be sent using the I_SETSIG ioctl{2) call [see 
streamio{7)]. Otherwise, the process will never receive SIGPOLL. 

For portability, applications should use only the symbolic names of signals 
rather than their values and use only the set of signals defined here. The 
action for the signal SIGKILL cannot be changed from the default system 
action. 

Specific implementations may have other implementation-defined signals. 
Also, additional implementation-defined arguments may be passed to the 
signal-catching handler for hardware-generated signals. For certain 



-3 - 



SIGSET(2) 



(C Software Development Set) 



SIGSET(2) 



hardware-generated signals, it may not be possible to resume execution at 
the point of interruption. 

The signal type SIGSEGV is reserved for the condition that occurs on an 
invalid access to a data object. If an implementation can detect this condi- 
tion, this signal type should be used. 

The other signal management functions, signal{2) and pause (2), should not 
be used in conjunction with these routines for a particular signal type. 

WARNING 

Two signals that behave differently from the signals described above exist in 
this release of the system: 

SIGCLD death of a child (reset when caught) 
SIGPWR power fail (not reset when caught) 

For these signals, func is assigned one of three values: SIG_DFL, SIG_IGN, 
or a function address. The actions prescribed by these values are as follows: 

SIG_DFL - ignore signal 

The signal is to be ignored. 

SIG_JGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the calling 
process's child processes will not create zombie processes when 
they terminate [see exit{2)]. 

sfunction address - catch signal 

If the signal is SIGPWR, the action to be taken is the same as that 
described above for func equal to function address. The same is 
true if the signal is SIGCLD with one exception: while the process 
is executing the signal-catching function, any received SIGCLD sig- 
nals will be ignored. (This is the default action.) 

The SIGCLD affects two other system calls [wait{2), and exit(2)] in the fol- 
lowing ways: 

wait If the func value of SIGCLD is set to SIG_JGN and a wait is exe- 
cuted, the wait will block until all of the calling process's child 
processes terminate; it will then return a value of -1 with errno set 
to ECHILD. 

exit If in the exiting process's parent process the func value of SIGCLD 
is set to SIG_IGN, the exiting process will not create a zombie pro- 
cess. 

When processing a pipeline, the shell makes the last process in the pipeline 
the parent of the preceding processes. A process that may be piped into in 
this manner (and thus become the parent of other processes) should take 
care not to set SIGCLD to be caught. 
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NAME 

Stat, fstat - get file status 

SYNOPSIS 

#include <8ys/t3rpes.h> 
#include <sys/stat.h> 

int Stat (path, buf) 
char ipath; 
struct Stat *buf; 

int fstat (fildes, buf) 
int fildes; 
struct Stat *buf; 

DESCRIPTION 

Path points to a path name naming a file. Read, write, or execute permis- 
sion of the named file is not required, but all directories listed in the path 
name leading to the file must be searchable. The stat system call obtains 
information about the named file. 

Note that in a Remote File Sharing environment, the information returned 
by Stat depends upon the user/group mapping set-up between the local and 
remote computers. [See idload{lM)]. 

Fstat obtains information about an open file known by the file descriptor 
fildes, obtained from a successful open, creat, dup, fcntl, or pipe system call. 
Buf is a pointer to a stat structure into which information is placed concern- 
ing the file. 

The contents of the structure pointed to by huf include the following 
members: 



ushort st_mode; 

ino_t st_Jno; 

dev__t sL_dev; 

dev_-t st_rdev; 



short 

ushort 

ushort 

off-t 

time_t 

time_t 

time_t 



st_nlink; 

st_uid; 

st_gid; 

st_size; 

st_atime; 

st__mtime; 

St— ctime; 



/* File mode [see mknod(l)\ */ 

/* Inode number */ 

/* ID of device containing */ 

/* a directory entry for this file */ 

/* ID of device */ 

/* This entry is defined only for */ 

/* character special or block special files */ 

/* Number of links */ 

/* User ID of the file's owner */ 

/* Group ID of the file's group */ 

/* File size in bytes */ 

/* Time of last access */ 

/* Time of last data modification */ 

/* Time of last file status change */ 

/* Times measured in seconds since */ 

/* 00:00:00 GMT, Jan. 1, 1970 */ 



st-mode The mode of the file as described in the mknod{2) system call. 

St— ino This field uniquely identifies the file in a given file system. The 
pair st_Jno and sL_dev uniquely identifies regular files. 
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st_jrdev 

St— nlink 
st_uid 
st-gid 
si_size 



st_dev This field uniquely identifies the file system that contains the 
file. Its value may be used as input to the ustat{2) system call to 
determine more information about this file system. No other 
meaning is associated v^ith this value. 

This field should be used only by administrative commands. It 
is valid only for block special or character special files and only 
has meaning on the system v^here the file was configured. 

This field should be used only by administrative commands. 

The user ID of the file's owner. 

The group ID of the file's group. 

For regular files, this is the address of the end of the file. For 
pipes or fifos, this is the count of the data currently in the file. 
For block special or character special, this is not defined. 

sL-atime Time when file data was last accessed. Changed by the follow- 
ing system calls: creat(2), mknod{2), pipe{2), utime{2), and 
read{2), 

st_mtime Time when data was last modified. Changed by the following 
system calls: creaf(2), mknod{2), pipe{2), utime{2\ and write{2), 

st-ctime Time when file status was last changed. Changed by the follow- 
ing system calls: chmod{2), chown{2), creat(2), link{2), mknodCl), 
pipe{2\ unlink(2), utime{2), and write{2). 

The Stat system call will fail if one or more of the following is true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path 

prefix. 

[EFAULT] Buf or path points to an invalid address. 

[EINTR] A signal was caught during the stat system call. 

[ENOLINK] Path points to a remote machine and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

Fstat will fail if one or more of the following is true: 
[EBADF] Fildes is not a valid open file descriptor. 

[EFAULT] Buf points to an invalid address. 

[ENOLINK] Fildes points to a remote machine and the link to that 
machine is no longer active. 

SEE ALSO 

chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2), read(2), time(2), 
unlink(2), utime(2), write(2). ^ ^ 
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DIAGNOSTICS 

Upon successful completion a value of is returned. Otherwise, a value of 
-1 is returned, and errno is set to indicate the error. 
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NAME 

statfs, fstatfs - get file system information 

SYNOPSIS 

#include <sy8/types.h> 
#include <sys/8tatfs.h> 

int statfs (path, buf, len, fstyp) 
char *psLth; 
struct statfs *buf; 
int len, fstyp; 

int fstatfs (fildes, buf, len, fstyp) 

int fildes; 

struct statfs *buf; 

int len, fstyp; 

DESCRIPTION 

The statfs system call returns a "generic superblock" describing a file sys- 
tem. It can be used to acquire information about mounted as well as 
unmounted file systems, and usage is slightly different in the two cases. In 
all cases, buf is a pointer to a structure (described below) which will be 
filled by the system call, and len is the number of bytes of information 
which the system should return in the structure. Len must be no greater 
than sizeof (struct statfs) and ordinarily it will contain exactly that value; if 
it holds a smaller value, the system will fill the structure with that number 
of bytes. (This allows future versions of the system to grow the structure 
without invalidating older binary programs.) 

If the file system of interest is currently mounted, path should name a file 
which resides on that file system. In this case the file system type is known 
to the operating system and the fstyp argument must be zero. For an 
unmounted file system path must name the block special file containing it 
and fstyp must contain the (non-zero) file system type. In both cases read, 
write, or execute permission of the named file is not required, but all direc- 
tories listed in the path name leading to the file must be searchable. 

The statfs structure pointed to by buf includes the following members: 

short f_Jstyp; /* File system type */ 

short f_bsize; /* Block size */ 

short f_Jrsize; /* Fragment size */ 

long f_blocks; /* Total number of blocks */ 

long f_bfree; /* Count of free blocks */ 

long f_files; /* Total number of file nodes */ 

long f_ffree; /♦ Count of free file nodes */ 

char f_fname[6]; /* Volume name */ 

char f_fpack[6]; /* Pack name */ 

The fstatfs system call is similar, except that the file named by path in statfs 
is instead identified by an open file descriptor fildes obtained from a suc- 
cessful openil), creat(2), dup{l), fcntl(l\ or pipe(l) system call. 
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The statfs system call obsoletes ustat(2) and should be used in preference to 
it in new programs. 

The statfs and fstatfs system calls will fail if one or more of the following is 
true: 

[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path 

prefix. 

[EFAULT] Buf or path points to an invalid address. 

[EBADF] Fildes is not a valid open file descriptor. 

[EINVAL] Fstyp is an invalid file system type; path is not a block spe- 

cial file and fstyp is nonzero; len is negative or is greater 
than sizeof (struct statfs). 

[ENOLINK] Path points to a remote machine, and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

chmod(2), chown(2), creat(2), link(2), mknod{2), pipe(2), read(2), time(2), 
unlink(2), utime(2), write(2), fs(4). 

DIAGNOSTICS 

Upon successful completion a value of is returned. Otherwise, a value of 
-1 is returned, and errno is set to indicate the error. 
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NAME 

stime - set time 

SYNOPSIS 

int stime (tp) 
long *tp; 

DESCRIPTION 

The stime system call sets the system's idea of the time and date. Tp points 
to the value of time as measured in seconds from 00:00:00 GMT Tanuarv 1 
1970. ^ 



[EPERM] stime will fail if the effective user ID of the calling process 

is not super-user. 

SEE ALSO 

time(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and ermo is set to indicate the error. 
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NAME 

sync - update super block 

SYNOPSIS 

void sync ( ) 

DESCRIPTION 

The sync system call causes all information in memory that should be on 
disk to be written out. This includes modified super blocks, modified 
inodes, and delayed block I/O. 

It should be used by programs which examine a file system, for example, 
fsck, df, etc. It is mandatory before a re-boot. 

The writing, although scheduled, is not necessarily complete upon return 
from sync. 
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NAME 

sysfs - get file system type information 

SYNOPSIS 

#include <sys/fstyp.h> 
#mclude <sys/fsid.h> 

int sysfs (opcode, fsname) 
int opcode; 
char *fsname; 

int sysfs (opcode, fs^ndex, buf) 
int opcode; 
int fs-index; 
char *buf; 



int sysfs (opcode) 
int opcode; 

DESCRIPTION 

The sysfs system call returns information about the file system types config- 
ured in the system. The number of arguments accepted by sysfs varies and 
depends on the opcode. The currently recognized opcodes and their functions 
are described below: 

GETFSIND translates fsname, a null-terminated file-system 

identifier, into a file-system type index. 

GETFSTYP translates fs-index, a file-system type index, into 

a null-terminated file-system identifier and writes 
it into the buffer pointed to by huf; this buffer 
must be at least of size FSTYPSZ as defined in 
<sys/fstyp.h>. 

GETNFSTYP returns the total number of file system types con- 

figured in the system. 

The sysfs system call will fail if one or more of the following is true: 

[EINVAL] Fsname points to an invalid file-system identifier; 

fs^index is zero, or invalid; opcode is invalid. 

[EFAULT] Buf or fsname point to an invalid user address. 

DIAGNOSTICS 

Upon successful completion, sysfs returns the file-system type index if the 
opcode is GETFSIND, a value of if the opcode is GETFSTYP, or the 
number of file system types configured if the opcode is GETNFSTYP. Oth- 
erwise, a value of -1 is returned, and ermo is set to indicate the error. 
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NAME 

sysi86 - machine-specific functions 

SYNOPSIS 

#include <sys/sysi86.h> 

int sysi86(cmd, arg) 
int cmd; 
char *arg; 

int sysi86(cmd, arg); 
int cmd; 
int arg; 

int sysi86(cmd, arg); 
int cmd; 
long arg; 

long sysi86(cmd, arg); 
int cmd; 

DESCRIPTION 

The sysi86 system call implements machine-specific functions. The cmd 
argument determines the function to be performed. The types of the argu- 
ments expected depend on the function. 

Command RTODC 

When cmd is RTODC, the expected argument is the address of a struct rtc—t 
(from the header file sys/rtch): 

struct rtc_t { 

char rtc_sec, rtc_asec, rtc_min, rtc_amin, 
rtcJhr, rtc_ahr, rtc_dow, rtc_dom, 
rtc_mon, rtc_yr, rtc_-Statusg, 
rtc_statusb, rtc_-statusc, rtc_statusd; 

}; 

This function reads the hardware time-of-day clock and returns the data in 
the structure referenced by the argument. This command is available only 
to the super-user. 

RDUBLK 

This command reads the u-block (per process user information as defined 
by structuser in the sys/user header file) for a given process. When cmd is 
RDUBLK, sysiSS takes three additional arguments: the process ID, the 
address of a buffer, and the number of bytes to read; i.e., 

sysi86(RDUBLK, pid, buf, n) 
int pid; 
char *buf; 
ind n; 

Command SI86FPHW 

This command expects the address of an integer as its argument. After suc- 
cessful return from the system call, the integer specifies how floating-point 
computation is supported. 



- 1 - 



SYSI86(2) 



(C Software Development Set) 



SYSI86(2) 



The low-order byte of the integer contains the value of "fpkind", a variable 
that specifies whether an 80287 or 80387 floating-point coprocessor is 
present, emulated in software, or not supported. The values are defined in 
the header file sys/fp.h. 

FP_NO no fp chip, no emulator (no fp support) 

FP_SW no fp chip, using software emulator 

FP_HW chip present bit 

FP_287 80287 chip present 

FP_387 80387 chip present 

Command SETNAME 

This command, which is only available to the super-user, expects an argu- 
ment of type char * which points to a NULL terminated string of at most 7 
characters. The command will change the running system's sysname and 
nodename [see uname{2)] to this string. 

Command STIME 

When cmd is STIME, an argument of type long is expected. This function 
sets the system time and date (not the hardware clock). The argument con- 
tains the time as measured in seconds from 00:00:00 GMT January 1, 1970. 
Note that this command is only available to the super-user. 

Command SI86DSCR 

This command sets a segment or gate descriptor in the kernel. The follow- 
ing descriptor types are accepted: 

• executable and data segments in the LDT at DPL 3 

• a call gate in the GDT at DPL 3 that points to a segment in the 
LDT 

The argument is a pointer to a request structure that contains the values to 
be placed in the descriptor. The request structure is declared in the 
sys/sysi86.h header file. 

Command SI86MEM 

This command returns the size of available memory in bytes. 

Command SI86SWPI 

When cmd is SI86SWPI, individual swapping areas may be added, deleted 
or the current areas determined. The address of an appropriately primed 
swap buffer is passed as the only argument. (Refer to sys/swap.h header 
file for details of loading the buffer.) 

The format of the swap buffer is: 

struct swapint { 

char si__cmd; /* command: SI_LIST, SI_ADD, SI_DEL */ 

char *si_buf; /* swap file path pointer */ 

int sL-swplo; /* start block */ 
int si_nblks; /* swap size */ 

} ' 

Note that the add and delete options of the command may only be exer- 
cised by the super-user. 
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Typically, a swap area is added by a single call to sysi86. First, the swap 
buffer is primed with appropriate entries for the structure members. Then 
sysi86 is invoked. 

#include <sys/sysi86.h> 
#include <sys/swap.h> 

struct swapint swapbuf; /*swap into buffer ptr*/ 
sysi86(SI86SWPI, &swapbuf); 

If this command succeeds, it returns to the calling process. This command 
fails, returning -1, if one or more of the following is true: 

[EFAULT] Swapbuf points to an invalid address 

[EFAULT] Swapbuf. si Jbuf points to an invalid address 

[ENOTBLK] Swap area specified is not a block special device 

[EEXIST] Swap area specified has already been added 

[ENOSPC] Too many swap areas in use (if adding) 

[ENOMEM] Tried to delete last remaining swap area 

[EINVAL] Bad arguments 

[ENOMEM] No place to put swapped pages when deleting a swap area 

SEE ALSO 

uname(2) 

swap(lM) in the User's /System Administrator's Reference Manual. 
DIAGNOSTICS 

Upon successful completion, the value of zero is returned; otherwise, -1 is 
returned, and errno is set to indicate the error. When the cmd is invalid, 
ermo is set to EINVAL. 
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NAME 

time - get time 

SYNOPSIS 

#include <sys/types.h> 

time_t time (tloc) 
long *tloc; 

DESCRIPTION 

The time system call returns the value of time in seconds since 00:00:00 
Greenvdch Mean Time (GMT), January 1, 1970. 

If tloc is non-zero, the return value is also stored in the location to which 
tloc points. 

SEE ALSO 

stime(2). 

DIAGNOSTICS 

Upon successful completion, time returns the value of time. Othervdse, a 
value of -1 is returned, and ermo is set to indicate the error. 

WARNING 

The time system call fails and its actions are undefined if tloc points to an 
illegal address. 
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NAME 

times - get process and child process times 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/times.h> 

long times (buffer) 
struct tms *buffer; 

DESCRIPTION 

The times system call fills the structure pointed to by buffer with time- 
accounting information. The following are the contents of this structure: 

struct tms { 

time_t tms_utime; 
time_t tms__stime; 
time_t tms— cutime; 
time_t tms—cstime; 

}; 

This information comes from the calling process and each of its terminated 
child processes for which it has executed a wait. All times are reported in 
clock ticks per second. Clock ticks are a system-dependent parameter. The 
specific value for an implementation is defined by the variable HZ, found in 
the include file param.h. 

Tms^utitne is the CPU time used while executing instructions in the user 
space of the calling process. 

Tms^time is the CPU time used by the system on behalf of the calling pro- 
cess. 

Tms—cutime is the sum of the tms—utimes and tms^cutimes of the child 
processes. 

Tms^cstime is the sum of the tmsstimes and tms-.cstimes of the child 
processes. 

[EFAULT] The times system call will fail if buffer points to an illegal 
address. 

SEE ALSO 

exec(2), fork(2), time(2), wait(2). 

DIAGNOSTICS 

Upon successful completion, times returns the elapsed real time, in clock 
ticks per second, from an arbitrary point in the past (e.g., system start-up 
time). This point does not change from one invocation of times to another. 
If times fails, a -1 is returned and ermo is set to indicate the error. Clock 
ticks occur 100 times per second. 
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NAME 

uadmin - administrative control 

SYNOPSIS 

#include <sys/uadmin.h> 

int uadmin (cmd, fen, mdep) 
int cmd, fen, mdep; 

DESCRIPTION 

The uadmin system call provides control for basic administrative functions. 
This system call is tightly coupled to the system administrative procedures 
and is not intended for general use. The argument mdep is provided for 
machine-dependent use and is not defined here. 

As specified by cmd, the following commands are available: 

A—SHUTDOWN The system is shutdovm. All user processes are killed, the 
buffer cache is flushed, and the root file system is 
unmounted. The action to be taken after the system has 
been shut down is specified by fen. The functions are gen- 
eric; the hardware capabilities vary on specific machines. 

AD_HALT Halt the processor. 

AD_BOOT Interactive reboot; user is prompted for system 
name. 

AD_IBOOT Interactive reboot; user is prompted for system 
name. 

The system stops immediately without any further process- 
ing. The action to be taken next is specified by fen as 
above. 

The root file system is mounted again after having been 
fixed. This should be used only during the startup process. 

A_SETCONFIG Sets the system configuration. Currently, only the follow- 
ing function is available: 

AD_PANICBOOT If mdep is 1, this function causes the 
machine to reboot automatically after a 
kernel panic. If mdep is 0, this function 
causes the machine to wait for user inter- 
vention at the console before rebooting 
after a kernel panic. 

The uadmin system call fails if any of the following is true: 
[EPERM] The effective user ID is not super-user. 



A_REBOOT 
A_REMOUNT 
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DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 

A_SHUTDOWN No return value. 

A_REBOOT No return value. 

A_REMOUNT 

A_SETCONFIG 

Otherv^ise, a value of -1 is returned, and ermo is set to indicate the error. 
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NAME 

ulimit - get and set user limits 

SYNOPSIS 

long ulimit (cmd, newlimit) 

int cmd; 

long newlimit; 

DESCRIPTION 

This function provides for control over process limits. The cmd values 
available are: 

1 Get the regular file size limit of the process. The limit is in units of 
512-byte blocks and is inherited by child processes. Files of any size 
can be read. 

2 Set the regular file size limit of the process to the value of newlimit. 
Any process may decrease this limit, but only a process with an effec- 
tive user ID of super-user may increase the limit, ulimit fails and the 
limit is unchanged if a process with an effective user ID other than 
super-user attempts to increase its regular file size limit. [EPERM] 

3 Get the maximum possible break value [see brk{2)]. 

4 Return configured value of NOFILES, the value for the maximum 
number of open files per process. 

SEE ALSO 

brk(2), write(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. Otherwise, a 
value of -1 is returned and ermo is set to indicate the error. 

WARNING 

ulimit is effective in limiting the growth of regular files. Pipes are currently 
limited to 5,120 bytes. 
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NAME 

umask - set and get file creation mask 

SYNOPSIS 

int umask (cmask) 
int cmask; 

DESCRIPTION 

The umask system call sets the process's file mode creation mask to cmask 
and returns the previous value of the mask. Only the low-order 9 bits of 
cmask and the file mode creation mask are used. 

SEE ALSO 

chmod(2), creat(2), mknod(2), open(2). 

mkdir{l), sh(l) in the User's/System Administrator's Reference Manual 
DIAGNOSTICS 

The previous value of the file mode creation mask is returned. 
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NAME 

umount - unmount a file system 

SYNOPSIS 

int umount (file) 
char *file; 

DESCRIPTION 

The umount system call requests that a previously mounted file system con- 
tained on the block special device or directory identified by file be 
unmounted. File is a pointer to a path name. After unmounting the file 
system, the directory upon which the file system was mounted reverts to its 
ordinary interpretation. 

The umount system call may be invoked only by the super-user. 

The umount system call will fail if one or more of the following is true: 

[EPERM] The process's effective user ID is not super-user. 

[EINVAL] File does not exist. 

[ENOTBLK] File is not a block special device. 

[EINVAL] File is not mounted. 

[EBUSY] A file on file is busy. 

[EFAULT] File points to an illegal address. 

[EREMOTE] File is remote. 

[ENOLINK] File is on a remote machine, and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of the path pointed to by file require hopping 
to multiple remote machines. 



A component of the path-prefix is not a directory. 
The named file does not exist. 



[ENOTDIR] 

[ENOENT] 

SEE ALSO 

mount(2). 

DIAGNOSTICS 

Upon successful completion a value of is returned. Otherwise, a value of 
-1 is returned and ermo is set to indicate the error. 



- 1 - 



UNAME(2) 



(C Software Development Set) 



UNAME(2) 



NAME 

uname - get name of current UNIX system 

SYNOPSIS 

#include <sys/utsname.h> 

int uname (name) 
struct utsname ^name; 

DESCRIPTION 

The uname system call stores information identifying the current UNIX sys- 
tem in the structure pointed to by name. 

The uname system call uses the structure defined in <sys/utsname.h> 
whose members are: 

char sysname[9]; 

char nodename[9]; 

char release[9]; 

char version[9]; 

char machine[9]; 

The uname system call returns a null-terminated character string naming the 
current UNIX system in the character array sysname. Similarly, nodename 
contains the name that the system is known by on a communications net- 
work. Release and version further identify the operating system. Machine 
contains a standard name that identifies the hardware that the UNIX system 
is running on. 

[EFAULT] uname will fail if name points to an invalid address. 
SEE ALSO 

uname(l) in the User's/System Administrator's Reference Manual. 
DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. Otherwise, a 
value of -1 is returned, and ermo is set to indicate the error. 
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NAME 

unlink - remove directory entry 

SYNOPSIS 

int unlink (path) 
char ipath; 

DESCRIPTION 

unlink removes the directory entry named by the path name pointed to by 
path. 

The named file is unlinked unless one or more of the following is true: 
[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path 

prefix. 

[EACCES] Write permission is denied on the directory containing the 

link to be removed. 

[EPERM] The named file is a directory and the effective user ID of 

the process is not super-user. 

[EBUSY] The entry to be unlinked is the mount point for a mounted 

file system. 

[ETXTBSY] The entry to be unlinked is the last link to a pure pro- 

cedure (shared text) file that is being executed. 

[EROFS] The directory entry to be unlinked is part of a read-only file 

system. 

[EFAULT] Path points outside the process's allocated address space. 

[EINTR] A signal was caught during the unlink system call. 

[ENOLINK] Path points to a remote machine and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

A file will not be unlinked when all of the following is true: 

the parent directory has the sticky bit set 

the file is not writable by the user 

the user does not own the parent directory 

the user does not own the file 

the user is not root 

When all links to a file have been removed and no process has the file 
open, the space occupied by the file is freed and the file ceases to exist. If 
one or more processes have the file open when the last link is removed, the 
removal is postponed until all references to the file have been closed. 

SEE ALSO 

close(2), link(2), open(2). 
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rm(l) in the Use fs /System Administrator* s Reference Manual. 
DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and ermo is set to indicate the error. 
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NAME 

ustat - get file system statistics 

SYNOPSIS 

#include <sys/types.h> 
#iiiclude <ustat.h> 



int ustat (dev, buf) 
dev_t dev; 
struct ustat *buf; 

DESCRIPTION 

The ustat system call returns information about a mounted file system. Dev 
is a device number identifying a device containing a mounted file system. 
Buf is a pointer to a ustat structure that includes the following elements: 

daddr_t f_tfree; /* Total free blocks */ 

ino_t f_tinode; /* Number of free inodes * / 

char f_fname[6]; /* Filsys name */ 

char f_fpack[6]; /* Filsys pack name */ 

The last two fields, f^name and f^fpack may not have significant informa- 
tion on all systems, and, in that case, will contain the null character. 

The ustat system call will fail if one or more of the following is true: 

[EINVAL] Dev is not the device number of a device containing a 

mounted file system. 

[EFAULT] Buf points outside the process's allocated address space. 

[EINTR] A signal was caught during a ustat system call. 

[ENOLINK] Dev is on a remote machine and the link to that machine is 
no longer active. 

[ECOMM] Dev is on a remote machine and the link to that machine is 

no longer active. 

SEE ALSO 

stat(2), fs(4). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and ermo is set to indicate the error. 
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NAME 

utime - set file access and modification times 

SYNOPSIS 

#include <sys/types.h> 
int utime (path, times) 
char *path; 

struct utimbuf *times; 
DESCRIPTION 

Path points to a path name naming a file. The utime system call sets the 
access and modification times of the named file. 

If times is NULL, the access and modification times of the file are set to the 
current time. A process must be the owner of the file or have write permis- 
sion to use utime in this manner. 

If times is not NULL, times is interpreted as a pointer to a utimbuf structure 
and the access and modification times are set to the values contained in the 
designated structure. Only the owner of the file or the super-user may use 
utime this way. 

The times in the following structure are measured in seconds since 00:00:00 
Greenwich Mean Time (GMT), Jan. 1, 1970. 

struct utimbuf { 

time_t actime; /* access time */ 
time_t modtime; /* modification time */ 

}; 

The utime system call will fail if one or more of the following is true: 
[ENOENT] The named file does not exist. 

[ENOTDIR] A component of the path prefix is not a directory. 
[EACCES] Search permission is denied by a component of the path 

prefix. 

[EPERM] The effective user ID is not super-user and not the owner of 

the file, and times is not NULL. 

[EACCES] The effective user ID is not super-user and not the owner of 

the file, and times is NULL and write access is denied. 

[EROFS] The file system containing the file is mounted read-only. 

[EFAULT] Times is not NULL and points outside the process's allo- 

cated address space. 
[EFAULT] Path points outside the process's allocated address space. 

[EINTR] A signal was caught during the utime system call. 

[ENOLINK] Path points to a remote machine, and the link to that 
machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 
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SEE ALSO 

stat(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Othervdse, a value of 
-1 is returned, and ermo is set to indicate the error. 
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NAME 

wait - wait for child process to stop or terminate 

SYNOPSIS 

int wait (stat_loc) 

int «stat— loc; 

int wait ((int *) 0) 

DESCRIPTION 

The wait system call suspends the calling process until one of the immedi- 
ate children terminates or until a child that is being traced stops, because it 
has hit a break point. The wait system call will return prematurely if a sig- 
nal is received and if a child process stopped or terminated prior to the call 
on wait; return is immediate. 

If stat—loc is non-zero, 16 bits of information called status are stored in the 
low order 16 bits of the location pointed to by statJioc, Status can be used 
to differentiate between stopped and terminated child processes and if the 
child process terminated, status identifies the cause of termination and 
passes useful information to the parent. This is accomplished in the follow- 
ing manner: 

If the child process stopped, the high order 8 bits of status will con- 
tain the number of the signal that caused the process to stop, and 
the low order 8 bits will be set equal to 0177. 

If the child process terminated due to an exit call, the low order 8 
bits of status will be zero, and the high order 8 bits will contain the 
low order 8 bits of the argument that the child process passed to 
exit [see exit{2)]. 

If the child process terminated due to a signal, the high order 8 bits 
of status will be zero, and the low order 8 bits will contain the 
number of the signal that caused the termination. In addition, if the 
low order seventh bit (i.e., bit 200) is set, a "core image" will have 
been produced [see signal{2)]. 

If a parent process terminates without waiting for its child processes to ter- 
minate, the parent process ID of each child process is set to 1. This means 
the initialization process inherits the child processes [see intro{2)]. 

The wait system call will fail and return immediately if one or more of the 
following is true: 

[ECHILD] The calling process has no existing unwaited-for child 

processes. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), pause(2), ptrace(2), signal(2). 
DIAGNOSTICS 

If wait returns due to the receipt of a signal, a value of -1 is returned to the 
calling process, and ermo is set to EINTR. If wait returns due to a stopped 
or terminated child process, the process ID of the child is returned to the 
calling process. Otherwise, a value of -1 is returned, and ermo is set to 
indicate the error. 
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WARNING 

The wait system call fails and its actions are undefined if stat—loc points to 
an invalid address. 
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NAME 

write - write on a file 

SYNOPSIS 

int write (fildes, buf, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 

DESCRIPTION 

fildes is a file descriptor obtained from a creat{l), open{2), dup{l), fcntl{l), or 
pipe (2) system call. 

The write system call attempts to write nbyte bytes from the buffer pointed 
to by buf to the file associated with the fildes. 

On devices capable of seeking, the actual writing of data proceeds from the 
position in the file indicated by the file pointer. Upon return from write, 
the file pointer is incremented by the number of bytes actually written. 

On devices incapable of seeking, writing always takes place starting at the 
current position. The value of a file pointer associated with such a device is 
undefined. 

If the 0_APPEND flag of the file status flags is set, the file pointer will be set 
to the end of the file prior to each write. 

For regular files, if the 0_SYNC flag of the file status flags is set, the write 
will not return until both the file data and file status have been physically 
updated. This function is for special applications that require extra reliabil- 
ity at the cost of performance. For block special files, if 0_SYNC is set, the 
write will not return until the data has been physically updated. 

A write to a regular file will be blocked if mandatory file/record locking is 
set [see chmod(^)], and there is a record lock owned by another process on 
the segment of the file to be written. If 0_NDELAY is not set, the write will 
sleep until the blocking record lock is removed. 

For STREAMS [see intro(2)] files, the operation of write is determined by the 
values of the minimum and maximum nbyte range ("packet size") accepted 
by the stream. These values are contained in the topmost stream module. 
Unless the user pushes [see LJPUSH in streamio{7)] the topmost module, 
these values cannot be set or tested from user level. If nbyte falls within the 
packet size range, nbyte bytes will be written. If nbyte does not fall within 
the range and the minimum packet size value is zero, write will break the 
buffer into maximum packet size segments prior to sending the data down- 
stream (the last segment may contain less than the maximum packet size). 
If nbyte does not fall within the range and the minimum value is non-zero, 
write will fail with errno set to ERANGE. Writing a zero-length buffer (nbyte 
is zero) sends zero bytes with zero returned. 

For STREAMS files, if 0_NDELAY is not set and the stream cannot accept 
data (the stream write queue is full due to internal flow control conditions), 
write will block until data can be accepted. 0_NDELAY will prevent a pro- 
cess from blocking due to flow control conditions. If 0_NDELAY is set and 
the stream cannot accept data, write will fail. If 0_NDELAY is set and part 
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of the buffer has been written when a condition in which the stream cannot 
accept additional data occurs, write will terminate and return the number of 
bytes written. 

The write system call will fail and the file pointer will remain unchanged if 
one or more of the following is true: 

[EAGAIN] Mandatory file/record locking was set, 0_NDELAY was set, 

and there was a blocking record lock. 

[EAGAIN] Total amount of system memory available when reading 

via raw lO is temporarily insufficient. 

[EAGAIN] Attempt to write to a stream that cannot accept data with 

the 0_NDELAY flag set. 

[EBADF] fildes is not a valid file descriptor open for writing. 

[EDEADLK] The write was going to go to sleep and cause a deadlock 
situation to occur. 

[EFAULT] buf points outside the process's allocated address space. 

[EFBIG] An attempt was made to write a file that exceeds the 

process's file size limit or the maximum file size [see 
ulimit{2)], 

[EINTR] A signal was caught during the write system call. 

[EINVAL] Attempt to write to a stream linked below a multiplexer. 

[ENOLCK] The system record lock table was full, so the write could 

not go to sleep until the blocking record lock was removed. 

[ENOLINK] fildes is on a remote machine and the link to that machine 
is no longer active. 

[ENOSPC] During a write to an ordinary file, there is no free space left 

on the device. 

[ENXIO] A hangup occurred on the stream being written to. 

[EPIPE and SIGPIPE signal] 

An attempt is made to write to a pipe that is not open for 

reading by any process. 

[ERANGE] Attempt to write to a stream with nbyte outside specified 

minimum and maximum write range, and the minimum 
value is non-zero. 

[EIO] A physical I/O error has occurred. 

If a write requests that more bytes be written than there is room for (e.g., 
the ulimit [see ulimit{2)] or the physical end of a medium), only as many 
bytes as there is room for will be written. For example, suppose there is 
space for 20 bytes more in a file before reaching a limit. A write of 512- 
bytes will return 20. The next write of a non-zero number of bytes will give 
a failure return (except as noted below). 

If the file being written is a pipe (or FIFO) and the 0_NDELAY flag of the file 
flag word is set, then write to a full pipe (or FIFO) will return a count of 0. 
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Otherwise (0_NDELAY clear), writes to a full pipe (or FIFO) will block until 
space becomes available. 

A write to a STREAMS file can fail if an error message has been received at 
the stream head. In this case, errno is set to the value included in the error 
message. 

SEE ALSO 

creat(2), dup(2), fcntl(2), intro(2), lseek(2), open(2), pipe(2), ulimit(2). 
DIAGNOSTICS 

Upon successful completion the number of bytes actually written is 
returned. Otherwise, -1 is returned, and ermo is set to indicate the error. 
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NAME 

intro - introduction to functions and libraries 
DESCRIPTION 

This section describes functions found in various libraries, other than those 
functions that directly invoke UNIX system primitives, which are described 
in Section 2 of this volume. Certain major collections are identified by a 
letter after the section number: 

(3C) These functions, together with those of Section 2 and those marked 
(3S), constitute the Standard C Library libc, which is automatically 
loaded by the C compiler, cc(l). (For this reason the (3C) and (3S) 
sections together comprise one section of this manual.) The link edi- 
tor ld{l) searches this library under the -Ic option. A "shared 
library" version of libc can be searched using the -lc_s option, 
resulting in smaller a.outs. Declarations for some of these functions 
may be obtained from #include files indicated on the appropriate 
pages. 

(3S) These functions constitute the "standard I/O package" [see stdio{3S)]. 
These functions are in the library libc, already mentioned. Declara- 
tions for these functions may be obtained from the #include file 
<stdio.h>. 

(3M) These functions constitute the Math Library, libm. They are not 
automatically loaded by the C compiler, cc(l); however, the link edi- 
tor searches this library under the -Im option. Declarations for these 
functions may be obtained from the #include file <math.h>. 
Several generally useful mathematical constants are also defined 
there [see math{5)], 

(3N) This contains sets of functions constituting the Network Services 
library. These sets provide protocol independent interfaces to net- 
working services based on the service definitions of the OSI (Open 
Systems Interconnection) reference model. Application developers 
access the function sets that provide services at a particular level. 

The function sets contained in the library are: 

TRANSPORT INTERFACE (TI)— provide the services of the OSI 
Transport Layer. These services provide reliable end-to-end data 
transmission using the services of an underlying network. Appli- 
cations written using the TI functions are independent of the 
underlying protocols. Declarations for these functions may be 
obtained from the #include file <tiuser.h>. The link editor 
ld(l) searches this library under the -InsL-S option. 

(3X) Various specialized libraries. The files in which these libraries are 
found are given on the appropriate pages. 

DEFINITIONS 

A character is any bit pattern able to fit into a byte on the machine. The 
null character is a character with value 0, represented in the C language as 
'\0'. A character array is a sequence of characters. A null-terminated charac- 
ter array is a sequence of characters, the last of which is the null character. 
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A string is a designation for a null-terminated character array. The null 
string is a character array containing only the null character. A NULL 
pointer is the value that is obtained by casting into a pointer. The C 
language guarantees that this value will not match that of any legitimate 
pointer, so many functions that return pointers return it to indicate an error. 
NULL is defined as in <stdio.h>; the user can include an appropriate 
definition if not using <stdio.h>. 

Netbuf 

In the Network Services library, netbuf is a structure used in various Tran- 
sport Interface (TI) functions to send and receive data and information. It 
contains the following members: 

unsigned int maxlen; 
unsigned int len; 
char *buf; 

Buf points to a user input and/or output buffer. Len generally specifies the 
number of bytes contained in the buffer. If the structure is used for both 
input and output, the function will replace the user value of len on return. 

Maxlen generally has significance only when huf is used to receive output 
from the TI function. In this case, it specifies the physical size of the buffer, 
the maximum value of len that can be set by the function. If maxlen is not 
large enough to hold the returned information, a TBUFOVFLW error will gen- 
erally result. However, certain functions may return part of the data and 
not generate an error. 

HLES 

LIBDIR usually /lib 

LIBDIR/libca 

LIBDIR/libc^.a 

LIBDIR/libm.a 

/shlib/libc-^ 

/shlib/libnsL_s (3N) 

/usr/lib/libnsLs.a (3N) 

SEE ALSO 

ar(l), cc(l), ld(l), lint(l), nm(l), intro(2), stdio(3S), math(5). 
DIAGNOSTICS 

Functions in the C and Math Libraries (3C and 3M) may return the conven- 
tional values or ±HUGE (the largest-magnitude single-precision floating- 
point numbers; HUGE is defined in the <math,h> header file) when the 
function is undefined for the given arguments or when the value is not 
representable. In these cases, the external variable ermo [see intro(2)] is set 
to the value EDOM or ERANGE. 

WARNING 

Many of the functions in the libraries call and/or refer to other functions 
and external variables described in this section and in Section 2 (System 
Calls). If a program inadvertentiy defines a function or external variable 
with the same name, the presumed library version of the function or 
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external variable may not be loaded. The lint(l) program checker reports 
name conflicts of this kind as "multiple declarations" of the names in ques- 
tion. Definitions for Sections 2, 3C, and 3S are checked automatically. 
Other definitions can be included by using the -1 option. (For example, -Im 
includes definitions for Section 3M, the Math Library.) Use of lint is highly 
recommended. 
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NAME 

a641, 164a - convert between long integer and base-64 ASCII string 

SYNOPSIS 

long a641 (s) 
char *s; 

char «164a (1) 
long 1; 

DESCRIPTION 

These functions are used to maintain numbers stored in base-64 ASCII char- 
acters. This is a notation by which long integers can be represented by up 
to six characters; each character represents a "digit" in a radix-64 notation. 

The characters used to represent "digits" are . for 0, / for 1, through 9 for 
2-11, A through Z for 12-37, and a through z for 38-63. 

The a64l function takes a pointer to a null-terminated base-64 representa- 
tion and returns a corresponding long value. If the string pointed to by s 
contains more than six characters, a64l will use the first six. 

The a64l function scans the character string from left to right, decoding each 
character as a 6-bit Radix 64 number. 

The I64a function takes a long argument and returns a pointer to the 
corresponding base-64 representation. If the argument is 0, I64a returns a 
pointer to a null string. 

CAVEAT 

The value returned by I64a is a pointer into a static buffer, the contents of 
which are overwritten by each call. 
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NAME 

abort - generate an abort fault 

SYNOPSIS 

int abort ( ) 

DESCRIPTION 

The abort function does the work of exit (2), but instead of just exiting, abort 
causes SIGABRT to be sent to the calling process. If SIGABRT is neither 
caught nor ignored, all stdio {3S) streams are flushed prior to the signal 
being sent, and a core dump results. 

The abort function returns the value of the kill (2) system call. 

SEE ALSO 

sdb(l), exit(2), kill{2), signal(2). 

DIAGNOSTICS 

If SIGABRT is neither caught nor ignored, and the current directory is writ- 
able, a core dump is produced and the message "abort - core dumped" is 
written by the shell. 
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NAME 

abs - return integer absolute value 

SYNOPSIS 

int abs (i) 
int i; 

DESCRIPTION 

The abs function returns the absolute value of its integer operand. 
SEE ALSO 

floor(3M). 

CAVEAT 

In two's-complement representation, the absolute value of the negative 
integer with largest magnihide is undefined. Some implementations trap 
this error, but others simply ignore it. 
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NAME 

assert - verify program assertion 

SYNOPSIS 

#include <assert.h> 

assert (expression) 
int expression; 

DESCRIPTION 

This macro is useful for putting diagnostics into programs. When it is exe- 
cuted, if expression is false (zero), assert prints 

"Assertion failed: expression, file xyz, line nnn" 

on the standard error output and aborts. In the error message, xyz is the 
name of the source file and nnn the source line number of the assert state- 
ment. 

Compiling with the preprocessor option -DNDEBUG [see cpp (1)], or with the 
preprocessor control statement "#define NDEBUG" ahead of the "#include 
<assert.h>" statement, will stop assertions from being compiled into the 
program. 

SEE ALSO 

cpp(l), abort(3C). 

CAVEAT 

Since assert is implemented as a macro, the expression may not contain any 
string literals. 
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NAME 

bessel: jO, jl, jn, yO, yl, yn - Bessel functions 

SYNOPSIS 

#include <math.h> 

double jO (x) 
double x; 

double jl (x) 
double x; 

double jn (n, x) 
int n; 
double x; 

double yO (x) 
double x; 

double yl (x) 
double x; 

double yn (n, x) 
int n; 
double x; 

DESCRIPTION 

JO and jl return Bessel functions of x of the first kind of orders and 1 
respectively. Jn returns the Bessel function of x of the first kind of order n. 

YO and yl return Bessel functions of x of the second kind of orders and 1 
respectively. Yn returns the Bessel function of x of the second kind of order 
n. The value of x must be positive. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

Non-positive arguments cause yO, yl, and yn to return the value -HUGE and 
to set ermo to EDOM. In addition, a message indicating DOMAIN error is 
printed on the standard error output. 

Arguments too large in magnitude cause yO, /I, yO, and yl to return zero 
and to set errno to ERANGE. In addition, a message indicating TLOSS error 
is printed on the standard error output. 

These error-handling procedures may be changed virith the function 
matherr{3M), 
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NAME 

bsearch - binary search a sorted table 

SYNOPSIS 

#include <search.h> 

char «bsearch ((char *) key, (char *) base, nel, sizeof (*key), compar) 
unsigned nel; 
int (♦compar)( ); 

DESCRIPTION 

The bsearch function is a binary search routine generalized from Knuth 
(6.2.1) Algorithm B. It returns a pointer into a table indicating where a 
datum may be found. The table must be previously sorted in increasing 
order according to a provided comparison function. Key points to a datum 
instance to be sought in the table. Base points to the element at the base of 
the table. Nel is the number of elements in the table. Compar is the name 
of the comparison function, which is called with two arguments that point 
to the elements being compared. The function must return an integer less 
than, equal to, or greater than zero if the first argument is to be considered 
less than, equal to, or greater than the second. 

EXAMPLE 

The example below searches a table containing pointers to nodes consisting 
of a string and its length. The table is ordered alphabetically on the string 
in the node pointed to by each entry. 

This code fragment reads in strings and either finds the corresponding node 
and prints out the string and its length, or prints an error message. 

#inclucle <stdio.h> 
#include <search.h> 

#define tabsize 1000 

struct node { /* these are stored in the table */ 

char ♦string; 
int length; 

} ; 

struct node table [ tabsize ] ; /* table to be searched */ 



{ 

struct node *node_ptr , node; 

int node_compare ( ); /♦ routine to compare 2 nodes */ 
char str_space [ 20 ] ; /* space to read string into */ 



node. string = str_space; 

while (scanf("%s", node. string) != EOF) { 

node_ptr = (struct node ♦) bsearch( ( char *)(&node), 
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(char ♦) table, tabsize, 
sizeof ( struct node), node_compare ) ; 
if (node_ptr 1= null) { 

(void)printf ( "string = 5620s, length = %d\n" , 
node_ptr->string, node_ptr->length) ; 

} else { 

( void)printf ( "not found: %s\n" , node . string ) ; 

> 

} 

} 

/♦ 

This routine compares two nodes based on an 
alphabetical ordering of the string field. 

*/ 

int 

node_compare ( node 1 , node2) 

char *node1, *node2; 

{ 

return (strcmp( 

((struct node *) node 1 ) ->string , 
((struct node *)node2 )— >string ) ) ; 

} 

SEE ALSO 

hsearch(3C), lsearch(3C), qsort(3C), tsearch(3C). 
DIAGNOSTICS 

A NULL pointer is returned if the key cannot be found in the table. 

NOTES 

The pointers to the key and the element at the base of the table should be 
of type pointer-to-element, and cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data 
may be contained in the elements in addition to the values being compared. 

Although bsearch is declared as type pointer-to-character, the value returned 
should be cast into type pointer-to-element. 
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NAME 

clock - report CPU time used 

SYNOPSIS 

long clock ( ) 

DESCRIPTION 

The clock function returns the amount of CPU time (in microseconds) used 
since the first call to clock. The time reported is the sum of the user and 
system times of the calling process and its terminated child processes for 
which it has executed wait(2), pclose{3S), or system{3S). 

The resolution of the clock is 10 milliseconds. 

SEE ALSO 

times{2), wait(2), popen(3S), system(3S). 

BUGS 

The value returned by clock is defined in microseconds for compatibility 
with systems that have CPU clocks with much higher resolution. Because 
of this, the value returned will wrap around after accumulating only 2147 
seconds of CPU time (about 36 minutes). 
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NAME 

crypt, setkey, encrypt - generate hashing encryption 

SYNOPSIS 

char *crypt (key, salt) 
char *key, «salt; 

void setkey (key) 
char *key; 

void encrypt (block, ignored) 
char "cblock; 
int ignored; 

DESCRIPTION 

The crypt function is the password encryption function. It is based on a 
one-way hashing encryption algorithm with variations intended (among 
other things) to frustrate use of hardware implementations of a key search. 

Key is a user's typed password. Salt is a two-character string chosen from 
the set [a-zA-ZO-9./]; this string is used to perturb the hashing algorithm in 
one of 4096 different ways, after which the password is used as the key to 
encrypt repeatedly a constant string. The returned value points to the 
encrypted password. The first two characters are the salt itself. 

The setkey and encrypt entries provide (rather primitive) access to the actual 
hashing algorithm. The argument of setkey is a character array of length 64 
containing only the characters with numerical value and 1. If this string is 
divided into groups of 8, the low-order bit in each group is ignored; this 
gives a 56-bit key which is set into the machine. This is the key that will 
be used with the hashing algorithm to encrypt the string block with the 
function encrypt. 

The argument to the encrypt entry is a character array of length 64 contain- 
ing only the characters with numerical value and 1. The argument array 
is modified in place to a similar array representing the bits of the argument 
after having been subjected to the hashing algorithm using the key set by 
setkey. Ignored is unused by encrypt but it must be present. 

SEE ALSO 

crypt(3X), getpass(3C), passwd(4). 

login(l), passwd(l) in the User's/System Administrator's Reference Manual 
CAVEAT 

The return value points to static data that are overwritten by each call. 
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NAME 

crypt - password and file encryption functions 

SYNOPSIS 

cc [flag ...] file ... -Icrypt 

char *crypt (key, salt) 
char *key, *salt; 

void setkey (key) 
char *key; 

void encrypt (block, flag) 
char *block; 
int flag; 

char *des-.crypt (key, salt) 
char *key, *salt; 

void des— setkey (key) 
char *key; 

void des^encrypt (block, flag) 
char ♦block; 
int flag; 

int run_setkey (p, key) 
int p[2]; 
char *key; 

int run— cr)rpt (offset, buffer, count, p) 
long offset; 
char *buffer; 
unsigned int count; 
int p[2]; 

int crypt_close(p) 
int p[2]; 

DESCRIPTION 

des^crypt is the password encryption function. It is based on a one-way 
hashing encryption algorithm with variations intended (among other things) 
to frustrate use of hardware implementations of a key search. 

Key is a user's typed password. Salt is a two-character string chosen from 
the set [a-zA-ZO-9./]. This string is used to perturb the hashing algorithm 
in one of 4096 different ways, after which the password is used as the key 
to encrypt repeatedly a constant string. The returned value points to the 
encrypted password. The first two characters are the salt itself. 

The dessetkey and des— encrypt entries provide (rather primitive) access to 
the actual hashing algorithm. The argument of des^etkey is a character 
array of length 64 containing only the characters with numerical value 
and 1. If this string is divided into groups of 8, the low-order bit in each 
group is ignored; this gives a 56-bit key which is set into the machine. This 
is the key that will be used with the hashing algorithm to encrypt the string 
block with the function des—encrypt , 
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The argument to the des— encrypt entry is a character array of length 64 con- 
taining only the characters with numerical value and 1. The argument 
array is modified in place to a similar array representing the bits of the 
argument after having been subjected to the hashing algorithm using the 
key set by des^etkey. If edflag is zero, the argument is encrypted; if non- 
zero, it is deoypted. 

Note that decryption is not provided in the international version of 
crypt{3X). The international version is part of the C Programming Language 
Utilities, and the domestic version is part of the Security Administration Util- 
ities, If decryption is attempted with the international version of 
des^encrypt, an error message is printed. 

Crypt, setkey, and encrypt are front-end routines that invoke des-crypt, 
des^etkey, and des^encrypt respectively. 

The routines runsetkey and run-crypt are designed for use by applications 
that need cryptographic capabilities [such as ed(l) and vi{l)] that must be 
compatible with the crypt{l) user-level utility. Runsetkey establishes a 
two-way pipe connection v^th crypt{\), using key as the password argument. 
Run^crypt takes a block of characters and transforms the cleartext or cipher- 
text using crypt{l). Offset is the relative byte position from the beginning of 
the file that the block of text provided in block is coming from. Count is the 
number of characters in block, and connection is an array containing indices 
to a table of input and output file streams. When encryption is finished, 
crypt-^close is used to terminate the connection with crypt{l), 

Runsetkey returns -1 if a connection with crypt{\) cannot be established. 
This will occur on international versions of the UNIX system where crypt{\) 
is not available. If a null key is passed to runsetkey, is returned. Other- 
wise, 1 is returned. Run^crypt returns -1 if it cannot write output or read 
input from the pipe attached to crypt. Otherwise it returns 0. 
SEE ALSO 

crypt(3C), getpass(3C), passwd(4). 

crypt(l), login(l), passwd(l) in the User's/System Administrator's Reference 
Manual, 

DIAGNOSTICS 

In the international version of crypt{3X), a flag argument of 1 to des^encrypt 
is not accepted, and an error message is printed. 
CAVEAT 

The return value in crypt points to static data that are overwritten by each 
call. 
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NAME 

ctermid - generate file name for terminal 

SYNOPSIS 

#include <stdio.h> 
char «ctermid (s) 
char *s; 

DESCRIPTION 

The ctermid function generates the path name of the controlling terminal for 
the current process and stores it in a string. 

If s is a NULL pointer, the string is stored in an internal static area, the con- 
tents of which are overwritten at the next call to ctermid, and the address of 
which is returned. Otherwise, s is assumed to point to a character array of 
at least L-.ctermid elements; the path name is placed in this array, and the 
value of s is returned. The constant L_ctermid is defined in the <stdio.h> 
header file. 

SEE ALSO 

ttyname(3C). 

NOTES 

The difference between ctermid and ttyname (3C) is that ttyname must be 
handed a file descriptor and returns the actual name of the terminal associ- 
ated v^th that file descriptor, while ctermid returns a string (/dev/tty) that 
will refer to the terminal if used as a file name. Thus ttyname is useful only 
if the process already has at least one file open to a terminal. 
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NAME 

ctime, localtime, gmtime, asctime, cftime, ascftime, tzset - convert date and 
time to string 

SYNOPSIS 

#include <sys/types.h> 
#include <time.h> 

char *ctime (clock) 
time—t «clock; 

struct tm *localtime (clock) 
time_t *clock; 

struct tm *gintime (clock) 
time__t *clock; 

char ♦asctime (tm) 
struct tm *tm; 

int cftime(buf, fmt, clock) 
char *buf, *fmt; 
timet *clock; 

int ascftime (buf, fmt, tm) 
char *buf, *fmt; 
struct tm *tm; 

extern long timezone, altzone; 
extern int daylight; 
extern char ♦tzname[2]; 
void tzset ( ) 
DESCRIPTION 

ctime, localtime, and gmtime accept arguments of type time— t (declared in 
<sys/types,h>), pointed to by clock, representing the time in seconds since 
00:00:00 Greenv^ich Mean Time (GMT), January 1, 1970. ctime returns a 
pointer to a 26-character string in the foUov^ing form. All the fields have 
constant vddth. 

Fri Sep 13 00:00:00 1986\n\0 

localtime and gmtime return pointers to "tm" structures, described below. 
localtime corrects for the main time zone and possible alternate ("Daylight 
Savings") time zone; gmtime converts directly to GMT, v^hich is the time 
the UNIX system uses. 

asctime converts a "tm" structure to a 26-character string, as shown in the 
above example, and returns a pointer to the string. 

Declarations of all the functions and externals, and the "tm" structure, are 
in the <time.h> header file. The structure declaration is: 

struct tm { 

int tm—sec; /* seconds after the minute — [0, 59] */ 

int tm-_min; /* minutes after the hour — [0, 59] */ 
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int 


tm_Jiour; 


int 


tm_mday; 


int 


tm mon; 


int 


tm_year; 


int 


tnL_wday; 


int 


tm— yday; 


int 


tm_isdst; 



/* hour since midnight — [0, 23] */ 
/* day of the month — [1, 31] */ 
/* months since January — [0, 11] */ 
/* years since 1900 */ 
/* days since Sunday — [0, 6] */ 
/* days since January 1 — [0, 365] */ 
/* flag for daylight savings time */ 

}; 

tm—isdst is non-zero if the alternate time zone is in effect. 

cftime and ascftime provide the capabilities of ctime and asctime, respec- 
tively, as well as additional ones, cftime takes an integer of type time—t 
pointed to by clock and converts it to a character string, ascftime takes a 
pointer to a "tm" structure and converts it to a character string. In both 
functions, the characters are placed into the array pointed to by buf (plus a 
terminating \0) and the value returned is the number of such characters (not 
counting the terminating \0). fmt controls the format of the resulting string. 

/mfis a character string that consists of field descriptors and text characters, 
reminiscent of printf{3S). Each field descriptor consists of a % character fol- 
lowed by another character which specifies the replacement for the field 
descriptor. All other characters are copied from fmt into the result. The fol- 
lowing field descriptors are supported: 

o/o% same as % 

%a abbreviated weekday name 

%A full weekday name 

%b abbreviated month name 

%B full month name 

o/od day of month ( 01 - 31 ) 

o/oD date as %m/%d/%y 

o/oe day of month (1-31; single digits are preceded by a blank) 

%h abbreviated month name 

o/oH hour ( 00 - 23 ) 

o/ol hour ( 00 - 12 ) 

%j day number of year ( 001 - 366 ) 

%m month number (01 - 12 ) 

o/oM minute ( 00 - 59 ) 

%n same as \n 

%p ante meridian or post meridian 

o/or time as %I:%M:%S %p 

o/oR time as %H:%M 

o/oS seconds ( 00 - 59 ) 

%t insert a tab 

%T time as %H:%M:%S 

%U week number of year (01 - 52 ), Sunday is the first day of week 

%w weekday number ( Sunday = ) 

%W week number of year (01-52 ), Monday is the first day of week 

%x Local specific date format 



-2- 



CTIME(3C) 



(C Software Development Set) 



CTIME(3C) 



%X 
%y 
%Y 



Local specific time format 
year within century ( 00 - 99 ) 
year as ccyy ( e.g. 1986) 
time zone name 



The difference between %U and %W lies in which day is counted as the 
first of the week. Week number 01 is the first week with four or more 
January days in it. 

The example below shows what the values in the "tm" structure would 
look like for Thursday, August 28, 1986, at 12:44:36 in New Jersey. 

ascftime (buf, "%A %m %d %j", tm) 

This example would result in the buffer containing "Thursday Aug 28 
240". 

If fmt is (char *)0, the value of the environment variable CFTIME is used. If 
CFTIME is undefined or empty, a default format is used. The default format 
string is taken from the file that contains the date and time strings associ- 
ated with the then current language [see below for details on changing the 
current language and cftime{4) for a description of the structure of these 
files]. 

The user can request that the output of cftime and ascftime be in a specific 
language by setting the environment variable LANGUAGE to the desired 
language. If LANGUAGE is empty, unset or set to an unsupported language, 
the last language requested will be used (the default is the usa-english 
strings). 

The external long variable timezone contains the difference, in seconds, 
between GMT and the main time zone; the external long variable altzone 
contains the difference, in seconds, between GMT and the alternate time 
zone; both, timezone and altzone default to (GMT). The external variable 
daylight is non-zero if an alternate time zone exists. The time zone names 
are contained in the external variable tzname , which by default is set to 

char *tzname[2] = { " gmt " , " " } ; 

The functions know about the peculiarities of this conversion for various 
time periods for the U.S.A (specifically, the years 1974, 1975, and 1987). 
The functions will handle the new daylight savings time starting with the 
first Sunday in April, 1987. 

tzset uses the contents of the environment variable TZ to override the value 
of the different external variables. The syntax of TZ can be described as fol- 
lows: 

TZ zone 



zone 

signed^time 



I zone signed^time 

I zone signed^time zone 

I zone signed^time zone dst 

letter letter letter 

sign time 
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I time 

time -* hour 

I hour : minute 

I hour : minute : second 

dst signed— time 

! signed— time ; dst— date , dst— date 
I ; dst— date , dst— date 

dst-date julian 

I julian I time 

letter a\A\b\B\...\z\Z 
hour 00 I 01 I ... I 23 

minute -> 00 \ Oil ... I 59 

second 00 I 01 I ... I 59 

julian 001 I 002 I ...I 366 

sign - 1 + 

tzset scans the contents of the environment variable and assigns the dif- 
ferent fields to the respective variable. For example, the setting for New Jer- 
sey in 1986 could be 

"EST5EDT4;117/2:00:00,299/2:00:00" . 

or simply 

EST5EDT 

A southern hemisphere setting such as the Cook Islands could be 
"KDT9:30KST10:00;64/5:00,303/20:00" 

When the longer format is used, the variable must be surrounded by double 
quotes as shown. For more details, see timezone(4) and environ(5). In the 
longer version of the New Jersey example of TZ, tzname[0] is EST, timezone 
will be set to 5*60*60, tzname[l] is EDT, altzone will be set to 4*60*60, the 
starting date of the alternate time zone is the 117th day at 2 AM, the ending 
date of the alternate time zone is the 299th day at 2 AM, and daylight will 
be set to non-zero. Starting and ending times are relative to the alternate 
time zone. If the alternate time zone start and end dates and the time are 
not provided, the days for the United States that year will be used and the 
time will be 2 AM. If the start and end dates are provided but the time is 
not provided, the time will be midnight. The effects of tzset are thus to 
change the values of the external variables timezone, altzone, daylight, and 
tzname. tzset is called by localtime and may also be called explicitly by the 
user. 

Note that in most installations, TZ is set to the correct value by default 
when the user logs on, via the local /etc/profile file [see profile{^)]. 

FILES 

/lib/cftime - directory that contains the language specific printable files 
SEE ALSO 

time(2), getenv{3C), putenv(3C), printf(3S), cftime(4), profile(4), timezone(4), 
environ(5). 
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CAVEAT 

The return values for ctime, localtime and gmtime point to static data whose 
content is overwritten by each call. 

Setting the time during the interval of change from timezone to altzone or 
vice versa can produce unpredictable results. 

The system administrator must change the Julian start and end days annu- 
ally if the full form of the TZ variable is specified. 



-5 - 



CTYPE(3C) 



(C Software Development Set) 



CTYPE(3C) 



NAME 

ctype: isdigit, isxdigit, islower, isupper, isalpha, isalnum, isspace, iscntrl, 
ispunct, isprint, isgraph, isascii, tolower, toupper, toascci, _tolower, 
_toupper, setchrclass - character handling 

SYNOPSIS 

#include <ctype.h> 

int isdigit (c); 
int c; 



tolower(c) 
int c; 



int setchrclass (chrclass) 
char «chrclass; 

DESCRIPTION 

The character classification macros listed below return nonzero for true, zero 
for false, isascii is defined on all integer values; the rest are defined on 
valid members of the character set and on the single value EOF [see 
stdio {3S)] (guaranteed not to be a character set member). 

isdigit tests for the digits through 9. 

isxdigit tests for any character for which isdigit is true or for the 

letters a through / or A through F. 
islower tests for any lowercase letter as defined by the character 

set. 

isupper tests for any uppercase letter as defined by the character 

set, 

isalpha tests for any character for which islower or isupper is true 

and possibly any others as defined by the character set. 

isalnum tests for any character for which isalpha or isdigit is true. 

isspace tests for a space, horizontal-tab, carriage return, newline, 

vertical-tab, or form-feed. 
iscntrl tests for "control characters" as defined by the character 

set. 

ispunct tests for any character other than the ones for which isal- 

num, iscntrl, or isspace is true or space. 

isprint tests for a space or any character for which isalnum or 

ispunct is true or other "printing character" as defined by 
the character set. 

isgraph tests for any character for which isprint is true, except for 

space. 

isascii tests for an ASCII character (a non-negative number less 

than 0200). 
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FILES 



The conversion functions and macros translate a character from lowercase 
(uppercase) to uppercase (lowercase). 

tolower if the character is one for which isupper is true and there is 

a corresponding lowercase character, tolower returns the 
corresponding lowercase character. Otherwise, the charac- 
ter is returned unchanged. 

toupper if the character is one for which islower is true and there is 

a corresponding uppercase character, toupper returns the 
corresponding uppercase character. Otherwise, the charac- 
ter is returned unchanged. 

toascii turns off the bits that are not part of the ASCII character set. 

-.tolower returns the lowercase representation of a character for 

which isupper is true, othervydse undefined. 

-toupper returns the uppercase representation of a character for 

which islower is true, othervdse undefined. 

The conversion macros have the same functionality of the functions on 
valid input, but the macros are faster because they do not do range check- 
ing. 

All the character classification macros and the conversion functions and 
macros do a table lookup. 

setchrclass initializes the table used by these functions and macros to a 
specific character classification set. setchrclass uses the value of its argu- 
ment or the value of the environment variable CHRCLASS as the name of 
the datafile containing the information for the desired character set. These 
datafiles are searched for in the special directory /lib/chrclass. 

If chrclass is (char *)0, the value of the environment variable CHRCLASS is 
used. If CHRCLASS is not set or is undefined, the table retains its current 
value, which at initialization time is ascii. 



/lib/chrclass - directory containing the datafiles for setchrclass 
SEE ALSO 

chrtbl(l), stdio(3S), ascii(5), environ(5). 
DIAGNOSTICS 

If the argument to any of the character handling macros is not in the 
domain of the function, the result is undefined. 

If setchrclass does not successfully fill the table, the table will not change 
(initially "ascii") and -1 is returned. If everything works, setchrclass 
returns 0. 

WARNING 

If a character variable or constant is passed to these functions or macros, 
undefined results may occur on machines which sign-extend characters by 
default. 
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NAME 

curses - terminal screen handling and optimization package 
SYNOPSIS 

The curses manual page is organized as follows: 

In SYNOPSIS 

- compiling information 

- summary of parameters used by curses routines 

- alphabetical list of curses routines, showing their parameters 

In DESCRIPTION: 

- An overview of how curses routines should be used 

In ROUTINES, each curses routine is described under the 
appropriate heading: 

- Overall Screen Manipulation 

- Window and Pad Manipulation 

- Output 

- Input 

- Output Options Setting 

- Input Options Setting 

- Environment Queries 

- Color Manipulation 

- Soft Labels 

- Low-level Curses Access 

- Terminfo-Level Manipulations 

- Termcap Emulation 

- Miscellaneous 

- Use of curscr 

Then come sections on: 

- ATTRIBUTES 

- COLORS 

- FUNCTION KEYS 

- LINE GRAPHICS 



cc [flag ...] file ... -Icurses [library ...] 

#include <curses.h> (automatically includes <stdio.h>, 

<termio.h>, and <unctrLh>). 

The parameters in the following list are not global variables, but rather 
this is a summary of the parameters used by the curses library routines. 
All routines return the int values ERR or OK unless otherwise noted. 
Routines that return pointers always return NULL on error. (ERR, OK, 
and NULL are all defined in <curses.h>.) 

bool bf 

char ♦*area,*boolnames[], *boolcodes[ ], *boolfnames[ ], *bp 
char *cap, *capname, codename[2], erasechar, *filename, *fmt 
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char *keyname, killchar, *label, *longname 

char *name, *numnames[], *numcodes[ ], *numfnames[] 

char *slk_label, *str, *stmames[], *strcodes[], *strfnames[] 

char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type 

chtype attrs, ch, horch, vertch 

FILE *infd, *outfd 

int begin_x, begin_y, begline, bot, c, col, count 

int dmaxcol, dmaxrow, dmincol, dminrow, *errret, fildes 

int (*init( )), labfmt, labnum, line 

int ms, ncols, new, newcol, newrow, nlines, numlines 

int oldcol, oldrow, overlay 

int pi, p2, p9, pmincol, pminrow, (*putc( )), row 
int smaxcol, smaxrow, smincol, sminrow, start 
int tenths, top, visibility, x, y 
short pair, f, b, color, r, g, b 

SCREEN *new, *newterm, *set_term 
TERMINAL *cur_term, *nterm, *oterm 
va_list varglist 

WINDOW *curscr, *dstwin, *initscr, *newpad, *newwin, *orig 
WINDOW *pad, *srcwin, *stdscr, *subpad, *subwin, *win 

addch(ch) 

addstr(str) 

attroff(attrs) 

attron(attrs) 

attrset(attrs) 

baudrate( ) 

beep( ) 

box(win, vertch, horch) 
caii.change-.coIor( ) 
cbreakO 
clear( ) 

clearok(win, bf) 
clrtobotO 
clrtoeol( ) 

color-_content(color, &r, &g, &b) 

copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol, 

dmaxrow, dmaxcol, overlay) 
curs-_set( visibility) 
deL_prog_mode( ) 
del^hell— mode( ) 
del— curterm(oterm) 
delay-_output(ms) 
delchO 
deletelnO 
delwin(win) 
doupdate( ) 
draino(ms) 
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echo( ) 
echochar(ch) 
endwin( ) 
erase( ) 
erasechar( ) 
filterO 
flashO 
flushinp( ) 

garbagedlines(win, begline, numlines) 

getbegyx(win, y, x) 

getchO 

getmaxyx(win, y, x) 
getstr(str) 
getsyx(y, x) 
getyx(win, y, x) 
halfdelay(tenths) 
has_colors( ) 
has— ic( ) 
has_il() 
idlok(win, bf) 
inchO 

init_color(color, r, g, b) 
init_pair(pair, f, b) 
initscr( ) 
insch{ch) 
insertln( ) 
intrflush(win, bf) 
isendwin( ) 
keynaine(c) 
keypad(win, bf) 
killcharO 
leaveok(win, bf) 
longname( ) 
meta(win, bf) 
move(y, x) 
mvaddch(y, x, ch) 
mvaddstr(y, x, str) 

mvcur(oldrow, oldcol, newrow, newcol) 
mvdelch(y, x) 
invgetch(y, x) 
mvgetstr(y, x, str) 
mvinch(y, x) 
mvinsch(y, x, ch) 
mvprintw(y, x, fmt [, arg...]) 
invscanw(y, x, fmt [, arg...]) 
invwaddch(win, y, x, ch) 
invwaddstr(win, y, x, str) 
mvwdelch(win, y, x) 
mvwgetch(win, y, x) 
mvwgetstr(win, y, x, str) 
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mvwin(win, y, x) 

mvwinch(win, y, x) 

mvwinsch(win, y, x, ch) 

mvwprintw(win, y, x, fmt [, arg...]) 

mvwscanw(win, y, x, fmt [, arg...]) 

napms(ms) 

newpad(nlines, ncols) 

newterm(type, outfd, infd) 

newwm(nlines, ncols, begin__y, begin_x) 

nl() 

nocbreak( ) 
nodelay(win, bf) 
noecho( ) 
noiil( ) 
noraw( ) 

notimeout(win, bf) 
overlay(srcwin, dstwin) 
overwrite(srcwin, dstwin) 
pair_content(pair, &f, &b) 
pechochar(pad, ch) 

pnoutre£resh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

pre£resh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

printw(fmt [, arg...]) 

putp(str) 

raw() 

refresh( ) 

reset_prog_mode( ) 
reset— shelL-mode( ) 
resetty( ) 

restartterm(term, fildes, errret) 
ripof£line(line, init) 
savetty( ) 

scanw(fmt [, arg...]) 

scr-_dump(filename) 

scr-Jnit(filename) 

scr_restore(filename) 

scroll(win) 

scrollok(win, bf) 

seL_ciirterm(nterm) 

set_tenn(new) 

8etscrreg(top, bot) 

setsyx(y, x) 

setupterin(term, fildes, errret) 

slk_clear( ) 

8lk_init(fmt) 

slk_Jabel(labnum) 

slk_noutrefresh( ) 

slk— refresh( ) 

slk_restore( ) 

slk_set(labnum, label, fmt) 
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slk_touch( ) 
standend( ) 
standout( ) 
start_color( ) 

subpad(orig, nlines, ncols, begin_y, begin_x) 

subwin(orig, nlines, ncols, begin_y, begin_x) 

tgetent(bp, name) 

tgetflag(codename) 

tgetnuin(codename) 

tgetstr(codename, area) 

tgoto(cap, col, row) 

tigetflag(capname) 

tigetnum(capname) 

tigetstr(capname) 

touchline(win, start, count) 

touch win(win) 

tparm(str, pi, p2, p9) 

tputs(str, count, putc) 

traceof£( ) 

traceon( ) 

t)rpeahead(fildes) 

unctrl(c) 

ungetch(c) 

vidattr(attrs) 

vidputs(attrs, putc) 

vwprintw(win, fmt, varglist) 

vwscanw(win, fmt, varglist) 

waddch(win, ch) 

waddstr(win, str) 

wattroff(win, attrs) 

wattron(win, attrs) 

wattrset(win, attrs) 

wclear(win) 

wclrtobot(win) 

wclrtoeol(win) 

wdelch(win) 

wdeleteln(win) 

wechochar(win, ch) 

werase(win) 

wgetch(win) 

wget8tr(win, str) 

winch(win) 

winsch(win, ch) 

winsertln(win) 

wmove(win, y, x) 

wnoutrefre8h(win) 

wprintw(win, fmt [, arg...]) 

wrefresh(win) 

wscanw(win, fmt [, arg...]) 

wsetscrreg(win, top, bot) 
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wstandend(win) 
wstandout(win) 

DESCRIPTION 

The curses routines give the user a terminal-independent method of updat- 
ing screens with reasonable optimization. 

The file <curses.h> must be included at the beginning of programs that use 
any curses routines. In addition, the routine initscr( ) or newterm( ) must be 
called before any of the other routines that deal with windows and screens 
are used. (Three exceptions are noted where they apply.) The routine 
endwinO must be called before exiting. To get character-at-a-time input 
without echoing (most interactive, screen-oriented programs want this), after 
calling initscrO you should call "cbreak(); noecho();" Most programs 
would additionally call "nonl(); intrflush (stdscr, FALSE); kevpad(stdscr, 
TRUE)/'. 

Before a curses program is run, a terminal's tab stops should be set and its 
initialization strings, if defined, must be output. To do this, execute tput 
init command after the shell environment variable TERM has been 
exported. For further detaUs, see profile{4), tput{ll and the "Tabs and Ini- 
tialization" subsection of terminfo{4). 

The curses library contains routines that manipulate data structures called 
windows that can be thought of as two-dimensional arrays of characters 
representing all or part of a terminal screen. A default window called stdscr 
is supplied, which is the size of the terminal screen. Others may be created 
with newwin(). Windows are referred to by variables declared as WIN- 
DOW *; the type WINDOW is defined in <curses.h> to be a structure. 
These data structures are manipulated with routines described below, 
among which the most basic are move() and addch(). (More general ver- 
sions of these routines are included with names beginning with w, allowing 
you to specify a window. The routines not beginning with w usually affect 
stdscr.) Then refresh() is called, telling the routines to make the user's ter- 
minal screen look like stdscr. The characters in a window are achially of 
type chtype, so that other information about the character may also be 
stored with each character. 

Special windows called pads may also be manipulated. These are windows 
which are not constrained to the size of the screen and whose contents need 
not be displayed completely. See the description of newpad( ) under "Win- 
dow and Pad Manipulation " for more information. 

In addition to drawing characters on the screen, video attributes may be 
included which cause the characters to be underlined or shown in reverse 
video on terminals that support such display enhancements. Line drawing 
characters may be specified to be output. On input, curses is also able to 
translate arrow and function keys that transmit escape sequences into single 
values. The video attributes, line drawing characters, and input values use 
names, defined in <curses.h>, such as A-REVERSE, ACS_HLINE, and 
KEY_LEFT. 

Routines that manipulate color on color alphanumeric terminals are new in 
this release of curses. To use these routines 8tart_color( ) must be called. 
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usually right after initscr( ). Colors are always used in pairs (referred to as 
color-pairs). A color-pair consists of a foregound color (for characters) and a 
background color (for the field the characters are displayed on). A program- 
mer initializes a color-pair with the routine iniL_pair(). After it has been 
initialized, COLOR— PAIR(n), a macro defined in <curse8.h>, can be used 
in the same ways other video attributes can be used. If a terminal is capa- 
ble of redefining colors the programmer can use the routine init_color( ) to 
change the definition of a color. The routines has— color() and 
can— change— color( ) return TRUE or FALSE, depending on whether the ter- 
minal has color capabilities and whether the user can change the colors. 
The routine color— content( ) allows a user to identify the amounts of red, 
green, and blue components in an initialized color. The routine 
pair— content( ) allows a user to find out how a given color-pair is currently 
defined. 

curses also defines the WINDOW * variable, curscr, which is used only for 
certain low-level operations like clearing and redrawing a garbaged screen, 
curscr can be used in only a few routines. If the window argument to 
clearok( ) is curscr, the next call to wrefresh( ) with any window will cause 
the screen to be cleared and repainted from scratch. If the window argu- 
ment to wrefreshO is curscr, the screen is immediately cleared and 
repainted from scratch. This is how most programs would implement a 
"repaint-screen" function. More information on using curscr is provided 
where its use is appropriate. 

The environment variables LINES and COLUMNS may be set to override 
terminfo's idea of how large a screen is. These may be used in an AT&T 
TELETYPE 5620 layer, for example, where the size of a screen is change- 
able. 

If the environment variable TERMINFO is defined, any program using curses 
will check for a local terminal definition before checking in the standard 
place. For example, if the environment variable TERM is set to att4425, then 
the compiled terminal definition is found in /usr/lib/terminfo/a/att4425. 
(The a is copied from the first letter of att4425 to avoid creation of huge 
directories.) However, if TERMINFO is set to $HOME/ my terms, curses will 
first check $HOME/myterms/a/att4425, and, if that fails, will then check 
/usr/lib/terminfo/a/att4425. This is useful for developing experimental 
definitions or when write permission on /usr/lib/terminfo is not available. 

The integer variables LINES and COLS are defined in <curses.h>, and will 
be filled in by initscr( ) with the size of the screen. (For more information, 
see the subsection "Terminfo-Level Manipulations".) The integer variables 
COLORS and COLOR—PAIRS are also defined in <curses.h> and contain, 
respectively, the maximum number of colors and color-pairs the tenninal 
can support. They are initialized by start— color( ). The constants TRUE and 
FALSE have the values 1 and 0, respectively. The constants ERR and OK are 
returned by routines to indicate whether the routine successfully completed. 
These constants are also defined in <curses.h>. 

ROUTINES 

Many of the following routines have two or more versions. The routines 
prefixed with w require a window argument. The routines prefixed with p 
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require a pad argument. Those without a prefix generally use stdscr. 

The routines prefixed with mv require y and x coordinates to n\ove to 
before performing the appropriate action. The mv( ) routines imply a call to 
move() before the call to the other routine. The window argument is 
always specified before the coordinates, y always refers to the row (of the 
window), and x always refers to the column. The upper left comer is 
always (0,0), not (1,1). The routines prefixed with mvw take both a window 
argument and y and x coordinates. 

In each case, win is the window affected and pad is the pad affected, (win 
and pad are always of type WINDOW *.) Option-setting routines require a 
boolean flag bf with the value TRUE or FALSE, (bf is always of type bool.) 
The types WINDOW, bool, and chtype are defined in <curses.h>. See the 
SYNOPSIS for a summary of what types all variables are. 

All routines return either the integer ERR or the integer OK, unless other- 
wise noted. Routines that return pointers always return NULL on error. 

Sometimes the description of a routine refers to a second routine. If the 
routine referred to is prefixed with a w, then you should assume that other 
versions of the second routine behave similarly. For example, the descrip- 
tion of initscrO refers to wrefresh(). This implies that the same result will 
occur if refresh( ) is called. 

Overall Screen Manipulation 

WINDOW «initscr( ) The first routine called should almost always be 
initscr( ). (The exceptions are slk_init( ), filter( ), and 
ripoffline( ).) This will determine the terminal type 
and initialize all curses data structures. initscr( ) also 
arranges that the first call to wrefresh( ) will clear the 
screen. If errors occur, initscr() will write an 
appropriate error message to standard error and exit; 
otherwise, a pointer to stdscr is returned. If the pro- 
gram wants an indication of error conditions, 
newtermO should be used instead of initscr(). 
initscr( ) should only be called once per application. 

endwinO A program should always call endwin() before exit- 

ing or escaping from curses mode temporarily, to do a 
shell escape or system{3S) call, for example. This rou- 
tine will restore tty(7) modes, move the cursor to the 
lower left comer of the screen and reset the terminal 
into the proper non-visual mode. To resume after a 
temporary escape, call wrefresh( ) or doupdate( ). 

isendwinO Retums TRUE if endwin() has been called without 

any subsequent calls to wrefresh( ). 

SCREEN *newterm(type, outfd, infd) 

A program that outputs to more than one terminal 
must use newterm() for each terminal instead of 
initscr( ). A program that wants an indication of error 
conditions, so that it may continue to mn in a line- 
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oriented mode if the terminal cannot support a 
screen-oriented program, must also use this routine. 
newtermO should be called once for each terminal. 
It returns a variable of type SCREEN* that should be 
saved as a reference to that terminal. The arguments 
are the type of the terminal to be used in place of the 
environment variable TERM; outfd, a stdio {3S) file 
pointer for output to the terminal; and infd, another 
file pointer for input from the terminal. When it is 
done running, the program must also call endwin() 
for each terminal being used. If newterm() is called 
more than once for the same terminal, the first termi- 
nal referred to must be the last one for which 
endwin( ) is called. 

SCREEN *set_tenn(new) 

This routine is used to switch between different termi- 
nals. The screen reference new becomes the new 
current terminal. A pointer to the screen of the previ- 
ous terminal is returned by the routine. This is the 
only routine which manipulates SCREEN pointers; all 
other routines affect only the current terminal. 

Window and Pad Manipulation 
refresh( ) 

wrefresh (win) These routines [or prefresh( ), pnoutrefresh( ), 
wnoutrefresh( ), or doupdate()] must be called to 
write output to the terminal, as most other routines 
merely manipulate data structures. wrefresh( ) copies 
the named window to the physical terminal screen, 
taking into account what is already there in order to 
nunimize the amount of information that's sent to the 
terminal (called optimization). refresh() does the 
same thing, except it uses stdscr as a default window. 
Unless leaveok() has been enabled, the physical cur- 
sor of the terminal is left at the location of the 
window's cursor. The number of characters output to 
the terminal is returned. 

Note that refresh( ) is a macro. 

wnoutrefresh(win) 

doupdate() These two routines allow multiple updates to the 

physical terminal screen with more efficiency than 
wrefreshO alone. How this is accomplished is 
described in the next paragraph. 

curses keeps two data structures representing the ter- 
minal screen: a physical terminal screen, describing 
what is actually on the screen, and a virtual terminal 
screen, describing what the programmer wants to 
have on the screen. wrefresh( ) works by first calling 
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wnoutrefresh( ), which copys the named window to 
the virtual screen, and then by calling doupdate(), 
which compares the virtual screen to the physical 
screen and does the actual update. If the programmer 
wishes to output several windows at once, a series of 
calls to wrefreshO will result in alternating calls to 
wnoutrefresh( ) and doupdate(), causing several 
bursts of output to the screen. By first calling 
wnoutrefresh( ) for each window, it is then possible 
to call doupdate( ) once, resulting in only one burst of 
output, with probably fewer total characters transmit- 
ted and certainly less processor time used. 

WINDOW *newwin(nlines, ncols, begin_y, begin_x) 

Create and return a pointer to a new window with 
the given number of lines (or rows), nlines, and 
columns, ncols. The upper left comer of the window 
is at line begin— y, column begins. If either nlines or 
ncols is 0, they will be set to the value of 
lines'begin—y and cols-begin— x, A new full-screen 
window is created by calling newwin(0,0,0,0). 

mvwin(win, y, x) Move the window so that the upper left comer will 
be at position (y, x). If the move would cause any 
portion of the window to be moved off the screen, it 
is an error and the window is not moved. 

WINDOW *subwin(orig, nlines, ncols, begirL_y, begirL_x) 

Create and retum a pointer to a new window with 
the given number of lines (or rows), nlines, and 
columns, ncols. The window is at position (begin— y, 
begin-x) on the screen. (This position is relative to 
the screen, and not to the window orig.) The window 
is made in the middle of the window orig, so that 
changes made to one window will affect the character 
image of both windows. When changing the image 
of a subwindow, it will be necessary to call 
touchwinO or touchIine() on orig before calling 
wrefresh( ) on orig. 

delwin(win) Delete the named window, freeing up all memory 

associated with it. If you try to delete a main window 
before all of its subwindows have been deleted, ERR 
will be retumed. 

WINDOW *newpad(nlines, ncols) 

Create and retum a pointer to a new pad data stmc- 
ture with the given number of lines (or rows), nlines, 
and columns, ncols. A pad is a window that is not 
restricted by the screen size and is not necessarily 
associated with a particular part of the screen. Pads 
can be used when a large window is needed, and 
only a part of the window will be on the screen at 
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one time. Automatic refreshes of pads (e.g. from 
scrolling or echoing of input) do not occur. It is not 
legal to call wrefresh() with a pad as an argument; 
the routines prefresh() or pnoutrefresh( ) should be 
called instead. Note that these routines require addi- 
tional parameters to specify the part of the pad to be 
displayed and the location on the screen to be used 
for display. 

WINDOW *8ubpad(orig, nlines, ncols, begin—y, begin_x) 

Create and return a pointer to a subwindow within a 
pad with the given number of lines (or rows), nlines, 
and columns, ncols. Unlike subwin(), which uses 
screen coordinates, the window is at position 
{begin— y, begin— x) on the pad. The window is made 
in the middle of the window orig, so that changes 
made to one window will affect the character image 
of both windows. When changing the image of a 
subwindow, it will be necessary to call touch win( ) or 
touchline( ) on orig before calling prefresh( ) on orig. 

prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 
pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 
These routines are analogous to wrefresh() and 
wnoutref resh( ) except that pads, instead of windows, 
are involved. The additional parameters are needed 
to indicate what part of the pad and screen are 
involved, pminrow and pmincol specify the upper left 
comer, in the pad, of the rectangle to be displayed. 
sminrow, smincol, smaxrow, and smaxcol specify the 
edges, on the screen, of the rectangle to be displayed 
in. The lower right comer in the pad of the rectangle 
to be displayed is calculated from the screen coordi- 
nates, since the rectangles must be the same size. 
Both rectangles must be entirely contained within 
their respective structures. Negative values of pmin- 
row, pmincol, sminrow, or smincol are treated as if 
they were zero. 

Output 

These routines are used to manipulate text in windows. 

addch(ch) 

waddch(win, ch) 

mvaddch(y, x, ch) 

mvwaddch(win, y, x, ch) 

The character ch is put into the window at the current 
cursor position of the window and the position of the 
window cursor is advanced. Its function is similar to 
that of putchar [see putc{3S)]. At the right margin, an 
automatic newline is performed. At the bottom of the 
scrolling region, if scrollok( ) is enabled, the scrolling 
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region will be scrolled up one line. 

If ch is a tab, newline, or backspace, the cursor will be 
moved appropriately within the window. A newline 
also does a wclrtoeol( ) before moving. Tabs are con- 
sidered to be at every eighth column. If ch is another 
control character, it will be drawn in the notation. 
(Calling winch() on a position in the window con- 
taining a control character will not return the control 
character, but instead will return one character of the 
representation of the control character.) 

Video attributes can be combined with a character by 
or-ing them into the parameter. This will result in 
these attributes also being set. (The intent here is that 
text, including attributes, can be copied from one 
place to another using winch() and waddch().) See 
wstandout( ), below. 

Note that ch is actually of type chtype, not a charac- 
ter. 

Note that addch(), mvaddch(), and mvwaddch(), are 
macros. 

echochar(ch) 
wechochar(win, ch) 

pechochar(pad, ch) These routines are functionally equivalent to a call to 
addch(ch) followed by a call to refresh(), a call to 
waddch(win, ch) followed by a call to wrefresh(win), 
or a call to waddch(pad, ch) followed by a call to 
prefresh(pad). The knowledge that only a single 
character is being output is taken into consideration 
and, for non-control characters, a considerable perfor- 
mance gain can be seen by using these routines 
instead of their equivalents. In the case of pecho- 
char(), the last location of the pad on the screen is 
reused for the arguments to prefresh( ). 

Note that ch is actually of t5^e chtype, not a charac- 
ter. 

Note that echochar( ) is a macro. 

addstr(str) 
waddstr(win, str) 
mvwaddstr(win, y, x, str) 

mvaddstr(y, x, str) These routines write all the characters of the null- 
terminated character string str on the given window. 
This is equivalent to calling waddch() once for each 
character in the string. 

Note that addstr(), mvaddstr(), and mvwaddstr() 
are macros. 
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attroff(attrs) 
wattroff(win, attrs) 
attron(attrs) 
wattron(win, attrs) 
attrset(attrs) 
wattrset(win, attrs) 
standend( ) 
wstandend(win) 
standout( ) 
wstandout(win) 



beep( ) 
flashO 



These routines manipulate the current attributes of 
the named window. These attributes can be any com- 
bination of the constants A^TANDOUT, 
A_REVERSE, A_BOLD, A_DIM, A^BLINK, 
A_UNDERLINE, and A_ALTCHARSET, as well as the 
macro COLOR-_PAIR(n). These attributes are defined 
in <curses.h> and can be combined with the C logi- 
cal OR ( I ) operator. 

The current attributes of a window are applied to all 
characters that are written into the window with 
waddch( ). Attributes are a property of the character, 
and move with the character through any scrolling 
and insert/delete line/character operations. To the 
extent possible on the particular terminal, they will be 
displayed as the graphic rendition of the characters 
put on the screen. 

wattrset(win, attrs) sets the current attributes of the 
given window to attrs. wattroff(win, attrs) turns off 
the named attributes without turning on or off any 
other attributes. wattron(win, attrs) turns on the 
named attributes without affecting any others. 
wstandout(win, attrs) is the same as wattron(win, 
A_STANDOUT). wstandend(win, attrs) is the same 
as wattrset(win, 0), that is, it turns off all attributes. 

Note that wattroff(), wattron(), wattrset(), wstan- 
dend(), and wstandout() return 1 at all times. 

Note that attrs is actually of type chtype, not a char- 
acter. 

Note that attroff(), attron{), attrset(), standend(), 
and standout( ) are macros. 

These routines are used to signal the terminal user. 
beepO will sound the audible alarm on the terminal, 
if possible, and if not, will flash the screen (visible 
bell), if that is possible. flash() will flash the screen, 
and if that is not possible, will sound the audible sig- 
nal. If neither signal is possible, nothing will happen. 
Nearly all terminals have an audible signal (bell or 



- 13 - 



CURSES(3X) (Extended Terminal Interface) CURSES(3X) 



beep) but only some can flash the screen. 

box(win, vertch, horch) 

A box is drawn around the edge of the window, win. 
vertch and horch are the characters the box is to be 
drawn with. If vertch and horch are 0, then appropri- 
ate default characters, ACS^VLINE and ACS__HLINE, 
will be used. 

Note that vertch and horch are actually of type 
chtype, not characters. 

These routines copy blanks to every position in the 
window. 

Note that erase( ) is a macro. 

These routines are like erase() and werase(), but they 
also call clearokO, arranging that the screen will be 
cleared completely on the next call to wrefresh() for 
that window, and repainted from scratch. 

Note that clear() is a macro. 

All lines below the cursor in this window are erased. 
Also, the current line to the right of the cursor, 
inclusive, is erased. 

Note that clrtobot( ) is a macro. 

The current line to the right of the cursor, inclusive, is 
erased. 

Note that clrtoeol( ) is a macro. 

delay_output(ms) Insert a ms millisecond pause in the output. It is not 
recommended that this routine be used extensively, 
because padding characters are used rather than a 
processor pause. 

delchO 
wdelch(win) 
invdelch(y, x) 

mvwdelch(win, y, x) The character under the cursor in the window is 
deleted. All characters to the right on the same line 
are moved to the left one position and the last charac- 
ter on the line is filled with a blank. The cursor posi- 
tion does not change (after moving to (y, x), if speci- 
fied). (This does not imply use of the hardware 
"delete-character" feature.) 

Note that delch(), mvdelch(), and mvwdelch() are 



erase( ) 
werase(win) 



clear( ) 
wclear(win) 



clrtobotO 
wclrtobot(win) 



clrtoeol( ) 
wclrtoeol(win) 
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macros. 



deleteln( ) 
wdeleteln(win) 



getyx(win, y, x) 



getbegyx(win, y, x) 
getmaxyx(win, y, x) 



insch(ch) 
winsch(win, ch) 
mvwinsch(win, y, 
mvinsch(y, x, ch) 



insertln( ) 
winsertln(win) 



The line under the cursor in the window is deleted. 
All lines below the current line are moved up one 
line. The bottom line of the window is cleared. The 
cursor position does not change. (This does not 
imply use of the hardware "delete-line" feature.) 

Note that deleteln( ) is a macro. 

The cursor position of the window is placed in the 
two integer variables y and x. 

Note that getyx() is a macro, so no is necessary 
before the variables y and x. 

The current beginning coordinates [getbegyx()] or size 
[getmaxyx( )] of the specified window are placed in 
the two integer variables y and x. 

Note that getbegyx( ) and getmaxyx( ) are macros, so 
no is necessary before the variables y and x. 



X, ch) 

The character ch is inserted before the character under 
the cursor. All characters to the right are moved one 
space to the right, losing the rightmost character of 
the line. The cursor position does not change (after 
moving to (y, x), if specified). (This does not imply 
use of the hardware "insert-character" feature.) 

Note that ch is actually of type chtype, not a charac- 
ter. 

Note that insch(), mvinsch(), and mvwinsch() are 
macros. 

A blank line is inserted above the current line and the 
bottom line is lost. (This does not imply use of the 
hardware "insert-line" feature.) 



move(y, x) 
winove(win, y, x) 



Note that msertln( ) is a macro. 

The cursor associated with the window is moved to 
line (row) y, column x. This does not move the phy- 
sical cursor of the terminal until wrefresh( ) is called. 
The position specified is relative to the upper left 
comer of the window, which is (0, 0). 

Note that move( ) is a macro. 
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overlay(srcwin, dstwin) 

overwrite(srcwin, dstwin) 

These routines overlay text from srcwin on top of text 
from dstwin wherever the two windows overlap. The 
difference is that overlay( ) is non-destructive (blanks 
are not copied), while overwrite( ) is destructive. 

copy win(srcwin, dstwin, sminrow, smincol, dminrow, dmincol, dmaxrow, 
dmaxcol, overlay) This routine provides finer control over the overlay( ) 
and overwriteO routines. As in the prefresh() rou- 
tine, a rectangle is specified in the destination win- 
dow, (dminrow, dmincol) and (dmaxrow, dmaxcol), and 
the upper-left-comer coordinates of the source win- 
dow, (sminrow, smincol). If the argument overlay is 
true, then copying is non-destructive, as in overlay( ). 

printw(fmt [, arg . . .]) 

wprintw(win, fmt [, arg . . .]) 

mvprmtw(y, x, fmt [, arg . . .]) 

mvwprmtw(win, y, x, fmt [, arg . . .]) 

These routines are analogous to printf(3). The string 
which would be output by printf(3) is instead output 
using waddstrO on the given window. 

vwprintw(win, fmt, varglist) 

This routine corresponds to vfprintf (3S). It performs a 
wprintwO using a variable argument list. The third 
argument is a va^ist, a pointer to a list of arguments, 
as defined in <varargs.h>. See the vprintf(3S) and 
varargs(5) manual pages for a detailed description on 
how to use variable argument lists. 

scroll(win) The window is scrolled up one line. This involves 

moving the lines in the window data structure. 

touchwin(win) 

touchline(win, start, count) 

Throw away all optimization information about which 
parts of the window have been touched, by pretend- 
ing that the entire window has been drawn on. This 
is sometimes necessary when using overlapping win- 
dows, since a change to one window will affect the 
other window, but the records of which lines have 
been changed in the other window will not reflect the 
change. touchline() only pretends that count lines 
have been changed, beginning with line start . 
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Input 

getchO 
wgetch(win) 
mvgetch(y, x) 

mvwgetch(win, y, x) A character is read from the terminal associated with 
the window. In NODELAY mode, if there is no input 
waiting, the value ERR is returned. In DELAY mode, 
the program will hang until the system passes text 
through to the program. Depending on the setting of 
cbreak(), this will be after one character (CBREAK 
mode), or after the first newline (NOCBREAK mode). 
In HALF-DELAY mode, the program will hang until a 
character is typed or the specified timeout has been 
reached. Unless noecho( ) has been set, the character 
will also be echoed into the designated window. 

When wgetch( ) is called, before getting a character, it 
will call wrefresh() if anything in the window has 
changed (for example, the cursor has moved or text 
changed). 

When using getch(), wgetch(), mvgetch(), or 
mvwgetch( ), do not set both NOCBREAK mode [noc- 
break()] and ECHO mode [echo()] at the same time. 
Depending on the state of the tty{7) driver when each 
character is typed, the program may produce undesir- 
able results. 

If wgetch() encounters a "O, it is returned (unlike 
stdio routines, which would return a null string and 
have a return code of -1). 

If ke)^ad(win, TRUE) has been called, and a function 
key is pressed, the token for that function key will be 
returned instead of the raw characters. (See keypad( ) 
under "Input Options Setting.") Possible function 
keys are defined in <curses.h> vdth integers begin- 
ning with 0401, whose names begin with KEY_. If a 
character is received that could be the beginning of a 
function key (such as escape), curses will set a timer. 
If the remainder of the sequence is not received 
within the designated time, the character will be 
passed through, otherwise the function key value will 
be returned. For this reason, on many terminals, 
there will be a delay after a user presses the escape 
key before the escape is returned to the program. 
(Use by a programmer of the escape key for a single 
character routine is discouraged. Also see 
notimeout( ) below.) 

Note that getch(), mvgetch(), and mvwgetch() are 
macros. 
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getstr(str) 

wgetstr(win, str) 

mvgetstr(y, x, str) 

mvwgetstr(win, y, x, str) 

A series of calls to wgetch( ) is made, until a newline, 
carriage return, or enter key is received. The resulting 
value (except for this terminating character) is placed 
in the area pointed at by the character pointer str. 
The user's erase and kill characters are interpreted. 
See wgetchO ^or how it handles characters differently 
from stdio routines (especially D). 

Note that getstr(), mvgetstr(), and mvwgetstr() are 
macros. 

ungetch(c) Place c onto the input queue, to be returned by the 

next call to wgetch( ). 

flushinp( ) Throws away any typeahead that has been typed by 

the user and has not yet been read by the program. 
Note that flushinp( ) will not throw away any charac- 
ters supplied by ungetch( ). 

inch( ) 
winch(win) 
mvinch(y, x) 

mvwinch(win, y, x) The character, of type chtype, at the current position 
in the named window is returned. If any attributes 
are set for that position, their values will be OR'ed 
into the value returned. The predefined constants 
A^CHARTEXT and A_ATTRIBUTES, defined in 
<curses.h>, can be used with the C logical AND (&) 
operator to extract the character or attributes alone. 

Note^ that inch(), winch(), mvinch(), and 
mvwinch( ) are macros. 

scanw(fmt [, arg...]) 

wscanw(win, fmt [, arg . . .]) 

mvscanw(y, x, fmt [, arg . . .]) 

mvwscanw(win, y, x, fmt [, arg . . .]) 

These routines correspond to scanf{3S\ as do their 
arguments and return values. wgetstr() is called on 
the window, and the resulting line is used as input for 
the scan. The return value for these routines is the 
number of arg values that are converted by fmt, arg 
values that are not converted are lost. See wgetstr( ) 
for how it handles strings differently from the stdio 
routines (especially *D). 

vwscanw(win, fmt, ap) 

This routine is similar to vwprintw() in that it per- 
forms a wscanwO using a variable argument list. 
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idlok(win, bf) 



The third argument is a va—list, a poir\ter to a list of 
arguments, as defined in <varargs.h>. See the 
vprintf{3S) and varargs{5) manual pages for a detailed 
description on how to use variable argument lists. 

Output Options Setting 

These routines set options within curses that deal with output. All options 
are initially FALSE, unless otherwise stated. It is not necessary to turn these 
options off before calling endwin( ). 

clearok(win, bf) If enabled (bf is TRUE), the next call to wrefresh( ) 
with this window will clear the screen completely and 
redraw the entire screen from scratch. This is useful 
when the contents of the screen are uncertain, or in 
some cases for a more pleasing visual effect. 

If enabled (bf is TRUE), curses will consider using the 
hardware "insert/delete-line" feature of terminals so 
equipped. If disabled {bf is FALSE), curses will very 
seldom use this feature. (The "insert/delete- 
character" feature is always considered.) This option 
should be enabled only if your application needs 
"insert/delete-line", for example, for a screen editor. 
It is disabled by default because "insert/delete-line" 
tends to be visually annoying when used in applica- 
tions where it isn't really needed. If "insert/delete- 
line" cannot be used, curses will redraw the changed 
portions of all lines. Not calling idlok() saves 
approximately 5000 bytes of memory. 

Normally, the hardware cursor is left at the location 
of the window cursor being refreshed. This option 
allows the cursor to be left wherever the update hap- 
pens to leave it. It is useful for applications where 
the cursor is not used, since it reduces the need for 
cursor motions. If possible, the cursor is made invisi- 
ble when this option is enabled. 

setscrreg(top, bot) 
wsetscrreg(win, top, bot) 

These routines allow the user to set a software scrol- 
ling region in a window, top and bot are the line 
numbers of the top and bottom margin of the scrol- 
ling region. (Line is the top line of the window.) If 
this option and scrollok() are enabled, an attempt to 
move off the bottom margin line will cause all lines in 
the scrolling region to scroll up one line. (Note that 
this has nothing to do with use of a physical scrolling 
region capability in the terminal, like that in the DEC 
VTIOO. Only the text of the window is scrolled; if 
idlok( ) is enabled and the terminal has either a scrol- 
ling region or "insert/delete-line" capability, they will 



leaveok(v^n, bf) 
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probably be used by the output routines.) 

Note that setscrreg( ) is a macro. 

scrollok(win, bf) This option controls what happens when the cursor of 
a window is moved off the edge of the window or 
scrolling region, either from a newline on the bottom 
line, or typing the last character of the last line. If 
disabled (bf is FALSE), the cursor is left on the bottom 
line at the location where the offending character was 
entered. If enabled (bf is TRUE), wref resh( ) is called 
on the window, and then the physical terminal and 
window are scrolled up one line. (Note that in order 
to get the physical scrolling effect on the terminal, it 
is also necessary to call idlok( ).) 

Note that scrollok( ) will always return OK. 

Input Options Setting 

These routines set options within curses that deal with input. The options 
involve using ioctl(2) and therefore interact with curses routines. It is not 
necessary to turn these options off before calling endwin( ). 

For more information on these options, see the chapter of the Programmer's 
Guide that describes how to write curses programs. 



cbreak( ) 
nocbreak( ) 



echo( ) 
noecho( ) 



These two routines put the terminal into and out of 
CBREAK mode, respectively. In CBREAK mode, char- 
acters typed by the user are immediately available to 
the program and erase/kill character processing is not 
performed. When in NOCBREAK mode, the tty driver 
will buffer characters typed until a newline or carriage 
return is typed. Interrupt and flow-control characters 
are unaffected by this mode [see termio{7)]. Initially 
the terminal may or may not be in CBREAK mode, as 
it is inherited, therefore, a program should call 
cbreakO or nocbreak() explicitly. Most interactive 
programs using curses will set CBREAK mode. 

Note that cbreak() performs a subset of the func- 
tionality of raw(). See wgetch() under "Input" for a 
discussion of how these routines interact with echo( ) 
and noecho( ). 

These routines control whether characters typed by 
the user are echoed by wgetch() as they are typed. 
Echoing by the tty driver is always disabled, but ini- 
tially wgetch( ) is in ECHO mode, so characters typed 
are echoed. Authors of most interactive programs 
prefer to do their own echoing in a controlled area of 
the screen, or not to echo at all, so they disable echo- 
ing by calling noecho(). See wgetch() under 
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nl() 
nonl() 



halfdelay(tenths) 



intrflush(win, bf) 



keypad(win, bf) 



meta(win, bf) 



nodelay(win, bf) 
notimeout(win, bf) 



"Input" for a discussion of how these routines 
interact with cbreak( ) and nocbreak( ). 

These routines control whether carriage return is 
translated into newline on input by wgetch(). Ini- 
tially, this translation is done; nonl() turns the trans- 
lation off. Note that translation by the tty(7) driver is 
disabled in CBREAK mode. 

Half-delay mode is similar to CBREAK mode in that 
characters typed by the user are immediately available 
to the program. However, after blocking for tenths 
tenths of seconds, ERR will be returned if nothing has 
been typed, tenths must be a number between 1 and 
255. Use nocbreak( ) to leave half-delay mode. 

If this option is enabled, when an interrupt key is 
pressed on the keyboard (interrupt, break, quit) all 
output in the tty driver queue will be flushed, giving 
the effect of faster response to the interrupt, but caus- 
ing curses to have the wrong idea of what is on the 
screen. Disabling the option prevents the flush. The 
default for the option is inherited from the tty driver 
settings. The window argument is ignored. 

This option enables curses to obtain information from 
the keypad of the user's terminal. If enabled, the user 
can press a function key (such as an arrow key) and 
wgetchO will return a single value representing the 
function key, as in KEY_LEFT. If disabled, curses will 
not treat function keys specially and the program 
would have to interpret the escape sequences itself. If 
the keypad in the terminal can be turned on (made to 
transmit), calling keypad {win, TRUE) will turn it on. 

Initially, whether the terminal returns 7 or 8 signifi- 
cant bits on input depends on the control mode of the 
tty driver [see termio{7)]. To force 8 bits to be 
returned, invoke meta {win, TRUE). To force 7 bits to 
be returned, invoke meta {win, FALSE). The window 
argument, win, is always ignored. If the terminfo{4) 
capabilities smm (meta— on) and rmm (meta_off) are 
defined for the terminal, smm will be sent to the ter- 
minal when meta {win, TRUE) is called and rmm will 
be sent when meta {win, FALSE) is called. 

This option causes wgetch() to be a non-blocking 
call. If no input is ready, wgetch() will return ERR. 
If disabled, wgetch( ) will hang until a key is pressed. 

While interpreting an input escape sequence, 
WgetchO will set a timer while waiting for the next 
character. If notimeout(z(; fn, TRUE) is called, then 
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raw() 
noraw( ) 



t3rpeahead(fildes) 



Environment Queries 
baudrate( ) 



char erasechar( ) 
has_ic( ) 



has_il() 



char killchar( ) 
char ♦longname( ) 



wgetchO will not set a timer. The purpose of the 
timeout is to differentiate between sequences received 
from a function key and those typed by a user. 

The terminal is placed into or out of RAW mode. RAW 
mode is similar to CBREAK mode, in that characters 
typed are immediately passed through to the user 
program; however, in RAW mode, the interrupt, quit, 
suspend, and flow control characters are passed 
through uninterpreted, instead of generating a signal 
as they do in CBREAK mode. The behavior of the 
BREAK key depends on other bits in the tty{7) driver 
that are not set by curses. 

curses does 'Tine-breakout optimization" by looking 
for typeahead periodically while updating the screen. 
If input is found, and it is coming from a tty, the 
current update will be postponed until wrefresh( ) or 
doupdateO is called again. This allows faster 
response to commands typed in advance. Normally, 
the file descriptor for the input FILE pointer passed to 
newtermO, or stdin in the case that initscr() was 
used, will be used to do this typeahead checking. 
The typeaheadQ routine specifies that the file 
descriptor fildes is to be used to check for typeahead 
instead. If fildes is -1, then no typeahead checking 
will be done. 

Note that fildes is a file descriptor, not a <stdio.h> 
FILE pointer. 

Returns the output speed of the terminal. The 
number returned is in bits per second, for example, 
9600, and is an integer. 

The user's current erase character is returned. 

True if the terminal has insert- and delete-character 
capabilities. 

True if the terminal has insert- and delete-line capa- 
bilities, or can simulate them using scrolling regions. 
This might be used to check to see if it would be 
appropriate to turn on physical scrolling using scrol- 
lok()oridlok(). 

The user's current line-kill character is returned. 

This routine returns a pointer to a static area contain- 
ing a verbose description of the current terminal. The 
maximum length of a verbose description is 128 char- 
acters. It is defined only after the call to initscr( ) or 
newterm(). The area is overwritten by each call to 
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newterm( ) and is not restored by set_terin( ), so the 
value should be saved between calls to newterm( ) if 
longnameO is going to be used with multiple termi- 
nals. 

Color Manipulation 

This section describes the color manipulation routines introduced in this 
release of curses. 

caiL-change-.color( ) This routine requires no arguments. It returns TRUE 
if the terminal supports colors and can change their 
definitions, FALSE otherwise. This routine facilitates 
writing terminal-independent programs. 

color_content(color, &r, &g, &b) 

This routine gives users a way to find the intensity of 
the red, green, and blue (RGB) components in a color. 
It requires four arguments: the color number, and 
three addresses of shorts for storing the information 
about the amounts of red, green, and blue com- 
ponents in the given color. The value of the first 
argument must be between and COLORS- 1. The 
values that will be stored at the addresses pointed to 
by the last three arguments will be between (no 
component) and 1000 (maximum amount of com- 
ponent). This routine returns ERR if the color does 
not exist (the first argument is outside the valid 
range), or if the terminal cannot change color defini- 
tions, OK otherwise. 

has_colors( ) This routine requires no arguments. It returns TRUE 

if the terminal can manipulate colors, FALSE other- 
wise. This routine facilitates writing terminal- 
independent programs. For example, a programmer 
can use it to decide whether to use color or some 
other video attribute. 

init_color(color, r, g, b) 

This routine changes the definition of a color. It takes 
four arguments: the number of the color to be 
changed followed by three RGB values (for the 
amounts of red, green, and blue components). (See 
the section COLOR for the default color index.) The 
value of the first argument must be between and 
COLORS- 1. The last three arguments must each be a 
value between and 1000. When init-_color( ) is 
used, all occurrences of that color on the screen 
immediately change to the new definition. It returns 
OK if it was able to change the definition of the color, 
ERR otherwise. 

init_pair(pair, f, b) This routine changes the definition of a color-pair. It 
takes three arguments: the number of the color-pair to 
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be changed, the foreground color number, and the 
background color number. The value of the first 
argument must be between 1 and COLOIL_PAIRS-l. 
The value of the second and third arguments must be 
between and COLORS-1. If the color-pair was pre- 
viously initialized, the screen will be refreshed and all 
occurrences of that color-pair will be changed to the 
new definition. The routine returns OK if it was able 
to change the definition of the color-pair, ERR other- 
wise. 

pair_content(pair, &f, &b) 

This routine allows users to find out what colors a 
given color-pair consists of. It requires three argu- 
ments: the color-pair number, and two addresses of 
shorts for storing the foreground and the background 
color numbers. The value of the first argument must 
be between 1 and COLOR_PAIRS-l. The values that 
will be stored at the addresses pointed to by the 
second and third arguments will be between and 
COLORS-1. The routine returns ERR if the color_pair 
has not been initialized, OK otherwise. 

start-coIor( ) This routine requires no arguments. It must be called 

if the user wants to use colors, and before any other 
color manipulation routine is called. It is good prac- 
tice to call this routine right after initscr(). 
starlL-Color( ) initializes eight basic colors (black, blue, 
green, cyan, red, magenta, yellow, and white), and 
two global variables, COLORS and COLORJPAIRS 
(respectively defining the maximum number of colors 
and color-pairs the terminal can support). It also 
restores the tenninal's colors to the values they had 
when the terminal was just turned on. It returns ERR 
if the terminal does not support colors, OK otherwise. 

Soft Labels 

If desired, curses will manipulate the set of soft function-key labels that exist 
on many terminals. For those terminals that do not have soft labels, if you 
want to simulate them, curses will take over the bottom line of stdscr, 
reducing the size of stdscr and the variable LINES, curses standardizes on 8 
labels of 8 characters each. If a curses program changes the values of the 
soft labels, it can restore them only to the default settings for that terminal. 
Therefore, if before calling a curses program a user changes the values of 
the soft labels, those values cannot be reset when the curses program ter- 
minates. 

slk_mit(labfmt) In order to use soft labels, this routine must be called 
before initscr() or newterm() is called. If initscr() 
winds up using a line from stdscr to emulate the soft 
labels, then labfmt determines how the labels are 
arranged on the screen. Setting labfmt to indicates 
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that the labels are to be arranged in a 3-2-3 arrange- 
ment; 1 asks for a 4-4 arrangement. 

slk--set(labnum, label, labfmt) 

labnum is the label number, from 1 to 8. label is the 
string to be put on the label, up to 8 characters in 
length. A NULL string or a NULL pointer will put up 
a blank label, labfmt is one of 0, 1 or 2, to indicate 
whether the label is to be left-justified, centered, or 
right-justified within the label. 

slk— refresh( ) 

slk— noutre^esh( ) These routines correspond to the routines wrefresh() 
and wnoutrefresh( ). Most applications would use 
slk-iioutrefresh( ) because a wrefresh() will most 
likely soon follow. 

char *slk_Jabel(labnum) 

The current label for label number labnum is returned, 
in the same format as it was in when it was passed to 
slk_set(); that is, how it looked prior to being justi- 
fied according to the labfmt argument of slk_set( ). 

The soft labels are cleared from the screen. 



slk_clear( ) 
slk_restore( ) 

slk_touch( ) 



are restored to the screen after a 



The soft labels 
slk_clear( ). 

All of the soft labels are forced to be output the next 
time a 8lk_noutrefresh( ) is performed. 

Low-Level curses Access 

The following routines give low-level access to various curses functionality. 
These routines typically would be used inside of library routines. 



deL-prog-jaiode( ) 
de£-shelL-mode( ) 



Save the current terminal modes as the "program" (in 
curses) or "shell" (not in curses) state for use by the 
reset_prog— mode( ) and reset_shelL_mode( ) rou- 
tines. This is done automatically by initscr( ). 



reset— prog_mode( ) 
reset— shell-jnode( ) 



resetty( ) 
savetty( ) 



getsyx(y, x) 



program" (in curses) or 
These are done automati- 



Restore the terminal to 
"shell" (out of curses) state 
cally by endwin( ) and doupdate( ) after an endwin( ), 
so they normally would not be called. 



These routines save and restore the state of the termi- 
nal modes. savettyO saves the current state of the 
terminal in a buffer and resetty( ) restores the state to 
what it was at the last call to savetty( ). 

The current coordinates of the virtual screen cursor 
are returned in y and x. If leaveok() is currently 
TRUE, then -1,-1 will be returned. If lines have been 
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removed from the top of the screen using ripoff- 
line( ), y and x include these lines; therefore, y and x 
should be used only as arguments for setsyx( ). 

Note that getsyx( ) is a macro, so no is necessary 
before the variables y and x. 

setsyx(y, x) The virtual screen cursor is set to y, x. If y and x are 

both -1, then leaveok( ) will be set. The two routines 
getsyxO and setsyx() are designed to be used by a 
library routine which manipulates curses windows but 
does not want to change the current position of the 
program's cursor. The library routine would call get- 
syx( ) at the beginning, do its manipulation of its own 
windows, do a wnoutrefresh( ) on its windows, call 
setsyx( ), and then call doupdate( ). 

ripof£Iine(line, init) This routine provides access to the same facility that 
slk_init() uses to reduce the size of the screen, rip- 
offlineO niust be called before initscr() or 
newtermO is called. If line is positive, a line will be 
removed from the top of stdscr; if negative, a line will 
be removed from the bottom. When this is done 
inside initscr(), the routine init{) is called with two 
arguments: a window pointer to the 1-line window 
that has been allocated and an integer with the 
number of columns in the window. Inside this initial- 
ization routine, the integer variables LINES and COLS 
(defined in <curses.h>) are not guaranteed to be 
accurate and wrefresh() or doupdate() must not be 
called. It is allowable to call wnoutrefresh( ) during 
the initialization routine. 

ripo££line( ) can be called up to five times before cal- 
ling initscr( ) or newterm( ). 

scr— dump(filename) The current contents of the virtual screen are written 
to the file filename. 

scr-_restore(filename) 

The virtual screen is set to the contents of filename, 
which must have been written using scr_dump(). 
ERR is returned if the contents of filename are not 
compatible with the current release of curses software. 
The next call to doupdate( ) will restore the screen to 
what it looked like in the dump file. 

scr-Jnit(filename) The contents of filename are read in and used to ini- 
tialize the curses data structures about what the termi- 
nal currently has on its screen. If the data is deter- 
mined to be valid, curses will base its next update of 
the screen on this information rather than clearing the 
screen and starting from scratch. scr_init( ) would be 
used after initscr() or a system{3S) call to share the 
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screen with another process which has done a 
scr_dump( ) after its endwin( ) call. The data will be 
declared invalid if the terminfo{4) capability nrrmc is 
true or the time-stamp of the tty is old. Note that 
keypadO, meta(), slk_clear(), curs_set(), flash(), 
and beepO do not affect the contents of the screen, 
but will make the tty's time-stamp old. 

The cursor state is set to invisible, normal, or very 
visible for visibility equal to 0, 1 or 2. If the terminal 
supports the visibility requested, the previous cursor 
state is returned; otherwise, 

is returned. 

Wait until the output has drained enough that it will 
only take ms more milliseconds to drain completely. 

garbagedlines(win, begline, numlines) 

This routine indicates to curses that a screen line is 
garbaged and should be thrown away before having 
anything written over the top of it. It could be used 
for programs such as editors which want a command 
to redraw just a single line. Such a command could 
be used in cases where there is a noisy communica- 
tions line and redrawing the entire screen would be 
subject to even more communication noise. Just 
redrawing the single line gives some semblance of 
hope that it would show up unblemished. The 
current location of the window is used to determine 
which lines are to be redrawn. 

napms(ms) Sleep for ms milliseconds. 

mvcur(oldrow, oldcol, newrow, newcol) 

Low-level cursor motion. 

Terminfo-Level Manipulations 

These low-level routines must be called by programs that need to deal 
directly with the terminfo(4:) database to handle certain terminal capabilities, 
such as programming function keys. For all other functionality, curses rou- 
tines are more suitable and their use is recommended. 

Initially, setupterm( ) should be called. (Note that setupterm( ) is automati- 
cally called by initscr() and newterm().) This will define the set of 
terminal-dependent variables defined in the terminfo{4) database. The ter- 
minfo(4) variables lines and columns [see tenninfo{4)] are initialized by 
setupterm( ) as follows: if the environment variables LINES and COLUMNS 
exist, their values are used. If the above environment variables do not exist 
and the program is running in a layer [see layers{l)], the size of the current 
layer is used. Otherwise, the values for lines and columns specified in the 
terminfo(4) database are used. 



curs—set( visibility) 



draino(ms) 
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The header files <curses.h> and <term.h> should be included, in this 
order, to get the definitions for these strings, numbers, and flags. 
Parameterized strings should be passed through tparm() to instantiate them. 
All terminfo{4) strings [including the output of tparm()] should be printed 
with tput8() or putp(). Before exiting, reseL_shell_mode( ) should be 
called to restore the tty modes. Programs which use cursor addressing 
should output enter-_ca_mode upon startup and should output 
exit_ca-jnode before exiting [see tenninfo(4)]. (Programs desiring shell 
escapes should call reseL_shelL-mode( ) and output exit_ca_mode before 
the shell is called and should output enter_ca_mode and call 
reset_prog_inode( ) after returning from the shell. Note that this is dif- 
ferent from the curses routines [see endwin( )]. 

setuptenn(term, fildes, errret) 

Reads in the terminfo{4) database, initializing the ter- 
minfo{4:) structures, but does not set up the output vir- 
tualization structures used by curses. The terminal 
type is in the character string term; if term is NULL, 
the environment variable TERM will be used. All out- 
put is to the file descriptor fildes. If errret is not 
NULL, then setupterm() will return OK or ERR and 
store a status value in the integer pointed to by errret. 
A status of 1 in errret is normal, means that the ter- 
minal could not be found, and -1 means that the ter- 
minfo(4) database could not be found. If errret is 
NULL, setupterm() will print an error message upon 
finding an error and exit. Thus, the simplest call is 
setupterm ((char *)0, 1, (int *)0), which uses all the 
defaults. 

The terminfo{4) boolean, numeric and string variables 
are stored in a structure of type TERMINAL. After 
setuptermO returns successfully, the variable 
cur_term (of type TERMINAL *) is initialized with all 
of the information that the terminfo(4) boolean, 
numeric and string variables refer to. The pointer 
may be saved before calling setupterm() again. 
Further calls to setupterm() will allocate new space 
rather than reuse the space pointed to by cur_term. 

set_curterm(nterm) nterm is of type TERMINAL *. set_curterm( ) sets the 
variable cur_term to nterm, and makes all of the ter- 
minfo(4:) boolean, numeric and string variables use the 
values from nterm. 

deL_curterm(oterm) oterm is of type TERMINAL *. deLcurterm() frees 
the space pointed to by oterm and makes it available 
for further use. If oterm is the same as cur—term, 
then references to any of the terminfo{^) boolean, 
numeric and string variables thereafter may refer to 
invalid memory locations until another setupterm() 
has been called. 
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restartterm(term, fildes, errret) 

Similar to setupterm(), except that it is called after 
restoring memory to a previous state; for example, 
after a call to scr_restore( ). It assumes that the win- 
dows and the input and output options are the same 
as when memory was saved, but the terminal type 
and baud rate may be different. 

char *tparin(str, p^, p^, . . p^) 

Instantiate the string str with parms p.. A pointer is 
returned to the result of str with t^e parameters 
applied. 

tputs(str, count, putc) 

Apply padding to the string str and output it. str 
must be a terminfo{4) string variable or the return 
value from tparm(), tgetstrQ, tigetstr() or tgoto(). 
count is the number of lines affected, or 1 if not appli- 
cable, putc is a putchar (3S)-like routine to which the 
characters are passed, one at a time. 

putp(str) A routine that calls tputs (str, 1, putchar). 

vidputs(attrs, putc) Output a string that puts the terminal in the video 
attribute mode attrs, which is any combination of the 
attributes listed below. The characters are passed to 
the putchar{3S)-\ike routine putc{). 

vidattr(attrs) Similar to vidputs(), except that it outputs through 

putchar{3S). 

The following routines return the value of the capability corresponding to 
the character string containing the terminfo{4t) capname passed to them. For 
example, rc = tigetstr("acsc") causes the value of acsc to be returned in rc. 

tigetflag(capname) The value -1 is returned if capname is not a boolean 
capability. The value is returned if capname is not 
defined for this terminal. 

tigetnum(capname) The value -2 is returned if capname is not a numeric 
capability. The value -1 is returned if capname is not 
defined for this terminal. 

tigetstr(capname) The value (char *) -1 is returned if capname is not a 
string capability. A null value is returned if capname 
is not defined for this terminal. 

char *boolnames[], *boolcodes[ ], *boolfnames[ ] 
char *numnames[], *numcodes[ ], *numfnames[ ] 
char *strnames[], *strcodes[], *strfnames[ ] 

These null-terminated arrays contain the capnames, 
the termcap codes, and the full C names, for each of 
the terminfo{A) variables. 

Termcap Emulation 

These routines are included as a conversion aid for programs that use the 
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termcap library. Their parameters are the same and the routines are emu- 
lated using the terminfo{4:) database. 

tgetent(bp, name) Look up termcap entry for name. The emulation 
ignores the buffer pointer bp. 

tgetflag(codename) Get the boolean entry for codename. 

tgetnum(codename) Get numeric entry for codename. 

char *tgetstr(codename, area) 

Return the string entry for codename. If area is not 
NULL, then also store it in the buffer pointed to by 
area and advance area. tputs() should be used to 
output the returned string. 

char *tgoto(cap, col, row) 

Instantiate the parameters into the given capability. 
The output from this routine is to be passed to 
tputs(). 

tputs(str, affcnt, putc) 

See tputs() above, under " Terminfo-Level Manipula- 
tions " . 



Turn off and on debugging trace output when using 
the debug version of the curses library, 
/usr/lib/lihdcurses.a. This facility is available only to 
customers with a source license. 

This macro expands to a character string which is a 
printable representation of the character c. Control 
characters are displayed in the notation. Printing 
characters are displayed as is. 

unctrlO is a macro, defined in <unctrLh>, which is 
automatically included by <curses.h>. 

char *keyname(c) A character string corresponding to the key c is 
returned. 

^ilter() This routine is one of the few that is to be called 

before initscr() or newterm() is called. It arranges 
things so that curses thinks that there is a 1-line 
screen, curses will not use any terminal capabilities 
that assume that they know what line on the screen 
the cursor is on. 

Use of curscr 

The special window curscr can be used in only a few routines. If the win- 
dow argument to clearok() is curscr, the next call to wrefresh() with any 
window will cause the screen to be cleared and repainted from scratch. If 
the window argument to wrefresh() is curscr, the screen is immediately 
cleared and repainted from scratch. (This is how most programs would 



Miscellaneous 
traceoff ( ) 
traceon( ) 



unctrl(c) 
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implement a "repaint-screen" routine.) The source window argument to 
overlayO, overwrite(), and copywin() may be curscr, in which case the 
current contents of the virtual terminal screen will be accessed. 

Obsolete Calls 

Various routines are provided to maintain compatibility in programs written 
for older versions of the curses library. These routines are all emulated as 
indicated below. 

crmode( ) Replaced by cbreak( ). 

fixterm( ) Replaced by reset-prog. ■.■mode( ). 

gettmode( ) A no-op. 

nocrmode( ) Replaced by nocbreak( ). 

resetterm( ) Replaced by reset_shelLjnode( ). 

saveterm( ) Replaced by def_prog-_mode( ). 

setterin( ) Replaced by setupterm( ). 

ATTRIBUTES 

The following video attributes, defined in <curses.h>, can be passed to the 
routines wattron( ), wattroff ( ), and wattrset( ), or OR'ed with the characters 
passed to waddch( ). 

Terminal's best highlighting mode 
Underlining 
Reverse video 
Blinking 
Half bright 
Extra bright or bold 
Alternate character set 

Color__pair defined in n (Note that this is a macro.) 



A_STANDOUT 

A_UNDERLINE 

A_REVERSE 

A_BLINK 

A_DIM 

A_BOLD 

A_ALTCHARSET 

COLOR_JPAIR(n) 



A_CHARTEXT 

A_ATTRIBUTES 

A_NORMAL 

A_COLOR 

PAIR_NUMBER(attrs) 



Bit-mask to extract character [described under winch( )] 

Bit-mask to extract attributes [described under winch( )] 

Bit mask to reset all attributes off 

(for example: wattrset (win, A_NORMAL) 

Bit-mask to extract color_pair field information 

Returns the pair number associated with the COLOR_PAIR(n) 

attribute. (Note that this is a macro.) 



COLORS 



In <curses.h> the following macros are defined to have the numeric value 
shown. These are the default colors, curses also assumes that color (zero) 
is the default background color for all terminals. 


1 
2 
3 
4 
5 
6 



COLOR-BLACK 

COLOR-BLUE 

COLOR-GREEN 

COLOR-CYAN 

COLOR-RED 

COLOR-MAGENTA 

COLOR-YELLOW 
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COLOR_WHITE 7 
FUNCTION KEYS 

The following function keys, defined in <curses.h>, might be returned by 
wgetchO if keypadO has been enabled. Note that not all of these may be 
supported on a particular terminal if the terminal does not transmit a unique 
code when the key is pressed or the definition for the key is not present in 
the terminfo{A) database. 



Name 


Value 


KEY_BREAK 


0401 


KEY_DOWN 


0402 


KEY_UP 


0403 


KEY_LEFT 


0404 


KEY__R1GHT 


0405 


KEY_HOME 


0406 


KEY-BACKSPACE 


0407 


KEY_FO 


0410 


KEY_F(n) 


(KEY_FO+(n)) 


KEY_DL 


0510 


KEY_IL 


0511 


KEY_DC 


0512 


KEY_IC 


0513 


KEY_EIC 


0514 


KEY_CLEAR 


0515 


KEY_EOS 


0516 


KEY_EOL 


0517 


KEY__SF 


0520 


KEY_SR 


0521 


KEY_NPAGE 


0522 


KEY_PPAGE 


0523 


KEY_STAB 


0524 


KEY_CTAB 


0525 


KEY_CATAB 


0526 


KEY_ENTER 


0527 


KEY_SRESET 


0530 


KEY_RESET 


0531 


KEY__PRINT 


0532 


KEY_LL 


0533 


KEY_A1 


0534 


KEY_A3 


0535 


KEY_B2 


0536 


KEY_C1 


0537 


KEY_C3 


0540 


KEY_BTAB 


0541 



Key name 

break key (unreliable) 
The four arrow keys . . . 



Home key (upward+left arrow) 
backspace (unreliable) 

Function keys. Space for 64 keys is reserved. 

Formula for f . 

Delete line 

Insert line 

Delete character 

Insert char or enter insert mode 

Exit insert char mode 

Clear screen 

Clear to end of screen 

Clear to end of line 

Scroll 1 line forward 

Scroll 1 line backwards (reverse) 

Next page 

Previous page 

Set tab 

Clear tab 

Clear all tabs 

Enter or send 

soft (partial) reset 

reset or hard reset 

print or copy 

home down or bottom (lower left) 
keypad is arranged like this: 

Al up A3 

left B2 right 

CI down C3 
Upper left of keypad 
Upper right of keypad 
Center of keypad 
Lower left of keypad 
Lower right of keypad 
Back tab key 
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KEY_BEG 


UD4Z 


Deg^inning^ Key 


KEY—CANCEL 




Cancel Key 


KEY_CLObb 






KEY_CUMMA1NJ U 






KEY_COPY 




copy Key 


Kb Y_CKb A 1 r. 


U^r^r/ 


v.rectLC jvcy 


KbY—hJNU 


kJDDV 


eiiu Kcy 


KEY—EXIT 


UODl 


exit Key 


KEY—FIND 




iiriQ Key 


TXT»N/ T TT?T T> 

KEY—HELP 




neip Key 


KEY—MARK 




iriarK Key 


KEY— MESSAGE 




message Key 


KEY— MOVE 


KjDDb 


move Key 


KEY— NEXT 




next ODjeci Key 


KEY— OPEN 


UooU 


op6n key 


KEY— OPTIONS 


U5ol 


options key 


KEY— PREVIOUS 




previous ODject Key 


KEY— REDO 


{JDOO 


redo key 


KEY— REFERENCE 


Udo4 


ref(erence) key 


KEY— REFKEbH 




reiresn Key 


KEY— REPLACE 


U5oo 


replace key 


KEY— RESTART 


Odd/ 


restart key 


KEY— RESUME 


UD/U 


resume key 


KEY— SAVE 


Ui>/1 


save key 


KEY—SBEG 




shifted beginning key 


KEY— SCANCEL 




sniitea cancel Key 


KEY— SCOMMAN D 


UD/4 


sniiieu commanu Key 


KEY— SCOPY 




sniiieu copy Key 


KEY— SCREATE 


UD/O 


sniiieQ creaie Key 


KEY— SDC 


ud// 


sniiieQ aeieie cnar Key 


KEY— SDL 


UoUU 


sniiieu ueiete iine Key 


KEY— SELECT 


UoUl 


select key 


KEY— SEND 


UoUZ 


sniiieu enu Key 


KEY— SEOL 


UoUa 


shifted clear line key 


KEY— SEXIT 


UoU4 


shifted exit key 


KEY— SFIND 


U6U5 


shifted find key 


KEY— SHELP 


0606 


shifted help key 


KEY— SHOME 


0607 


shifted home key 


KEY—SIC 


0610 


shifted input key 


KEY-SLEFT 


0611 


shifted left arrow key 


KEY-SMESSAGE 


0612 


shifted message key 


KEY—bMUVE 


Uolo 


sniiieci move Key 


KEY-SNEXT 


0614 


shifted next key 


KEY-SOPTIONS 


0615 


shifted options key 


KEY-SPREVIOUS 


0616 


shifted prev key 


KEY-SPRINT 


0617 


shifted print key 


KEY-SREDO 


0620 


shifted redo key 


KEY-SREPLACE 


0621 


shifted replace key 


KEY-SRIGHT 


0622 


shifted right arrow 


KEY-SRSUME 


0623 


shifted resume key 
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KEY_SSAVE 


0624 


KEY_SSUSPEND 


0625 


KEY_SUNDO 


0626 


KEY_SUSPEND 


0627 


KEY_UNDO 


0630 



shifted save key 
shifted suspend key 
shifted undo key 
suspend key 
undo key 

LINE GRAPHICS 

The following variables may be used to add line-drav^ing characters to the 
screen with waddch(). When defined for the terminal, the variable will 
have the A_ALTCHARSET bit himed on. Otherwise, the default character 
listed below will be stored in the variable. The names were chosen to be 
consistent with the DEC VTIOO nomenclature. 



Name 



Default Glyph Description 



ACS_ULCORNER 

ACS_LLCORNER 

ACS_URCORNER 

ACS_LRCORNER 

ACS_RTEE 

ACS_LTEE 

ACS_BTEE 

ACS_TTEE 

ACS_HLINE 

ACS_VLINE 

ACS-PLUS 

ACS_S1 

ACS_S9 

ACS_DIAMOND 

ACS_CKBOARD 

ACS_DEGREE 

ACS_PLMINUS 

ACS-BULLET 

ACS_LARROW 

ACS-RARROW 

ACS-D ARROW 

ACS-UARROW 

ACS-BOARD 

ACS-LANTERN 

ACS-BLOCK 



+ upper left corner 

+ lower left comer 

+ upper right comer 

+ lower right comer 

+ right tee ( -I) 

+ left teed-) 

+ bottom tee ( J_) 

+ top tee (T) 

- horizontal line 

I vertical line 

+ plus 

scan line 1 

scan line 9 

+ diamond 

: checker board (stipple) 
degree symbol 

# plus/minus 
o bullet 
< arrow pointing left 
> arrow pointing right 
V arrow pointing down 

arrow pointing up 

# board of squares 

# lantem s)mibol 

# solid square block 

SEE ALSO 

cc(l), ld(l), ioctl(2), plot(3X), putc(3S), scanf(3S), stdio(3S), system(3S), 
vprintf(3S), profile(4), term(4), terminfo(4), varargs(5). 

termio(7), tty(7) in the User's/System Administrator's Reference Manual. 

Chapter 10 of the Programmer's Guide, 

DIAGNOSTICS 

All routines retum the integer OK upon successful completion and the 
integer ERR upon failure, unless otherwise noted in the preceding routine 
descriptions. 
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All macros return the value of their w version, except getsyx(), getyx(), 
getbegyx( ), getmaxyx( ). For these macros, no useful value is returned. 

Routines that return pointers always return (type *) NULL on error. 

WARNINGS 

To use the new curses features, use the Release 3.1 version of curses on 
UNIX System V Release 3.1. All programs that ran with Release 2 or 
Release 3.0 curses will also run on UNIX System V Release 3.1. You can 
link applications with object files based on Release 2 or Release 3.0 
curses / terminfo with the Release 3.1 libcurses.a library; however, you cannot 
link applications with object files based on Release 3.1 curses /terminfo with 
the Release 2 or Release 3.0 libcurses.a library. 

The plotting library plot{3X) and the curses library curses{3X) both use the 
names erase() and move(). The curses versions are macros. If you need 
both libraries, put the plot(3X) code in a different source file from the 
curses(3X) code, and/or #undef move() and eraseO in the plot{3X) code. 

Between the time a call to initscr( ) and endwin( ) has been issued, use only 
the routines in the curses library to generate output. Using system calls or 
the "standard I/O package" [see stdio {3S)] for output during that time can 
cause unpredictable results. 

If a pointer passed to a routine as a window argument is null or out of 
range, the results are undefined (core may be dumped). 

BUGS 

Currently typeahead checking is done using a nodelay read followed by an 
ungetch( ) of any character that may have been read. Typeahead checking 
is done only if wgetch() has been called at least once. This may change 
when proper kernel support is available. Programs which use a mixture of 
their own input routines with curses input routines may wish to call typea- 
head(-l) to turn off typeahead checking. 

The argument to napms( ) is currently rounded up to the nearest second, 
draino (ms) only works for ms equal to 0. 
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NAME 

cuserid - get character login name of the user 

SYNOPSIS 

#include <stdio.h> 

char *cuserid (s) 
char 'i's; 

DESCRIPTION 

The cuserid function generates a character-string representation of the login 
name that the owner of the current process is logged in under. If s is a 
NULL pointer, this representation is generated in an internal static area, the 
address of which is returned. Otherwise, s is assumed to point to an array 
of at least L_cuserid characters; the representation is left in this array. The 
constant L.cuserid is defined in the <stdio.h> header file. 

SEE ALSO 

getlogin(3C), getpwent(3C). 

DIAGNOSTICS 

If the login name cannot be found, cuserid returns a NULL pointer; if s is not 
a NULL pointer, a null character (\0) will be placed at s[0]. 
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NAME 

dial - establish an outgoing terminal line connection 

SYNOPSIS 

#include <dial.h> 

int dial (call) 
CALL call; 

void undial (fd) 
int fd; 

DESCRIPTION 

dial returns a file-descriptor for a terminal line open for read/write. The 
argument to dial is a CALL structure (defined in the <dialh> header file). 

When finished with the terminal line, the calling program must invoke 
undial to release the semaphore that has been set during the allocation of 
the terminal device. 

The definition of CALL in the <dial.h> header file is: 
typedef struct { 

struct termio *attr; /* pointer to termio attribute struct */ 

int baud; /* transmission data rate */ 

int speed; /* 212A modem: low=300, high=1200 */ 

char *line; /* device name for outgoing line */ 

char *telno; /* pointer to tel-no digits string */ 

int modem; /* specify modem control for direct lines */ 

char *device; /* unused */ 

int dev_len; /* unused */ 

} CALL; 

The CALL element speed is intended only for use with an outgoing dialed 
call, in which case its value should be either 300 or 1200 to identify the 
113 A modem, or the high- or low-speed setting on the 21 2A modem. Note 
that the 113 A modem or the low-speed setting of the 2 12 A modem will 
transmit at any rate between and 300 bits per second. However, the 
high-speed setting of the 21 2 A modem transmits and receives at 1200 bits 
per second only. The CALL element baud is for the desired transmission 
baud rate. For example, one might set baud to 110 and speed to 300 (or 
1200). However, if speed is set to 1200, baud must be set to high (1200). 

If the desired terminal line is a direct line, a string pointer to its device- 
name should be placed in the line element in the CALL structure. Legal 
values for such terminal device names are kept in the Devices file. In this 
case, the value of the baud element should be set to -1. This will cause dial 
to determine the correct value from the Devices file. 

The telno element is for a pointer to a character string representing the tele- 
phone number to be dialed. Such numbers may consist only of these char- 
acters: 

0-9 dial 0-9 

* dial * 

# dial # 
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= wait for secondary dial tone 

- delay for approximately 4 seconds 

The CALL element modem is used to specify modem control for direct lines. 
This element should be non-zero if modem control is required. The CALL 
element attr is a pointer to a termio structure, as defined in the termio.h 
header file. A NULL value for this pointer element may be passed to the 
dial function, but if such a structure is included, the elements specified in it 
will be set for the outgoing terminal line before the connection is esta- 
blished. This is often important for certain attributes such as parity and 
baud-rate. 

The CALL elements device and dev—len are no longer used. They are 
retained in the CALL structure for compatibility reasons. 

FILES 

/usr /lib /uucp /Devices 
/usr/lib /uucp /Systems 
/usr /spool /locks /LCK. . tty -device 

SEE ALSO 

alarm(2), read(2), write(2). 

uucp(lC), termio(7) in the User's/System Administrator's Reference Manual. 
DIAGNOSTICS 

On failure, a negative value indicating the reason for the failure will be 
returned. Mnemonics for the negative indices as listed here are defined in 
the <dial.h> header file. 



INTRPT 


-1 


D__HUNG 


-2 


NO_ANS 


-3 


ILL_BD 


-4 


A_PROB 


-5 


L_PROB 


-6 


NO_Ldv 


-7 


DV_NT_A 


-8 


DV_NT_K 


-9 


NO_BD_JS^ 


-10 


NO_BD_K 


-11 


DV__NT_E 


-12 


BAD_SYS 


-13 



WARNINGS 

Including the dial.h header file 



/* interrupt occurred */ 

/* dialer hung (no return from write) */ 

/* no answer within 10 seconds */ 

/* illegal baud-rate */ 

/* acu problem (open() failure) */ 

/* line problem (open() failure) */ 

/* can't open Devices file */ 

/* requested device not available */ 

/* requested device not known */ 

/* no device available at requested baud */ 

/* no device known at requested baud */ 

/* requested speed does not match */ 

/* system not in Systems file*/ 

automatically includes the termio, h header 



file. 

The above routine uses stdio.h, which causes it to increase the size of pro- 
grams not otherwise using standard I/O, more than might be expected. 
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BUGS 

An alarm{l) system call for 3600 seconds is made (and caught) within the 
dial module for the purpose of "touching" the LCK.. file and constitutes the 
device allocation semaphore for the terminal device. Otherwise, uucp (IC) 
may simply delete the LCK.. entry on its 90-minute clean-up rounds. The 
alarm may go off while the user program is in a read{l) or write (2) system 
call, causing an apparent error return. If the user program expects to be 
around for an hour or more, error returns from reads should be checked for 
(errno==EINTR), and the read possibly reissued. 
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NAME 

directory: opendir, readdir, telldir, seekdir, rewinddir, closedir - directory 
operations 

SYNOPSIS 

#include <sys/types.h> 
#include <dirent.h> 

DIR I'opendir (filename) 
char *£iiename; 

struct dirent ^readdir (dirp) 
DIR *diip; 

long telldir (dirp) 
DIR *dirp; 

void seekdir (dirp, loc) 
DIR *dirp; 
long loc; 

void rewinddir (dirp) 
DIR *dirp; 

void closedir(dirp) 
DIR *dirp; 

DESCRIPTION 

Opendir opens the directory named by filename and associates a directory 
stream with it. Opendir returns a pointer to be used to identify the directory 
stream in subsequent operations. The pointer NULL is returned if filename 
cannot be accessed or is not a directory, or if it cannot malloc enough 
memory to hold a DIR structure or a buffer for the directory entries. 

Readdir returns a pointer to the next active directory entry. No inactive 
entries are returned. It returns NULL upon reaching the end of the directory 
or upon detecting an invalid location in the directory. 

Telldir returns the current location associated with the named directory 
stream. 

Seekdir sets the position of the next readdir operation on the directory 
stream. The new position reverts to the one associated with the directory 
stream when the telldir operation from which loc was obtained was per- 
formed. Values returned by telldir are good only if the directory has not 
changed due to compaction or expansion. This is not a problem with Sys- 
tem V, but it may be with some file system types. 

Rewinddir resets the position of the named directory stream to the beginning 
of the directory. 

Closedir closes the named directory stream and frees the DIR structure. 
The following errors can occur as a result of these operations. 
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opendir: 
[ENOTDIR] 
[EACCES] 
[EMFILE] 

[EFAULT] 



A component of filename is not a directory. 

A component of filename denies search permission. 

The maximum number of file descriptors are currently 
open. 

Filename points outside the allocated address space. 



readdir: 
[ENOENT] 

[EBADF] 



The current file pointer for the directory is not located at a 
valid entry. 

The file descriptor determined by the DIR stream is no 
longer valid. This results if the DIR stream has been 
closed. 



telldir, seekdir, and closedir: 

[EBADF] The file descriptor determined by the DIR stream is no 

longer valid. This results if the DIR stream has been 
closed. 

EXAMPLE 

Sample code which searches a directory for entry name: 

dirp = opendir( "." ); 

while ( (dp = readdir( dirp )) != NULL ) 

if ( strcmp( dp->d__name, name ) == ) 

{ 

closedir( dirp ); 
return FOUND; 

} 

closedir( dirp ); 
return NOT_FOUND; 



SEE ALSO 

getdents(2), dirent(4). 

WARNINGS 

Rewinddir is implemented as a macro, so its function address cannot be 
taken. 



-2- 



DRAND48(3C) 



(C Software Development Set) 



DRAND48(3C) 



NAME 

drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, 
lcong48 - generate uniformly distributed pseudo-random numbers 

SYNOPSIS 

double drand48 ( ) 

double erand48 (xsubi) 
unsigned short xsubi[3]; 

long lrand48 ( ) 

long nrand48 (xsubi) 
unsigned short xsubi[3]; 

long mrand48 ( ) 

long jrand48 (xsubi) 
unsigned short xsubi[3]; 

void srand48 (seedval) 
long seedval; 

unsigned short *seed48 (seedl6v) 
unsigned short seedl6v[3]; 

void lcong48 (param) 
unsigned short param[7]; 

DESCRIPTION 

This family of functions generates pseudo-random numbers using the well- 
known linear congruential algorithm and 48-bit integer arithmetic. 

Functions drand48 and erand48 return non-negative double-precision 
floating-point values uniformly distributed over the interval [0.0, 1.0). 

Functions lrand48 and nrand48 return non-negative long integers uniformly 
distributed over the interval [0, 2^^). 

Functions mrand48 and jrand48 return signed long integers uniformly distri- 
buted over the interval [-2^^ 2^^). 

Functions srand48, seed48, and lcong48 are initialization entry points, one of 
which should be invoked before either drand48, lrand48, or mrand48 is 
called. (Although it is not recommended practice, constant default initializer 
values will be supplied automatically if drand48, lrand48, or mrand48 is 
called without a prior call to an initialization entry point.) Functions 
erand48, nrand48, and jrand48 do not require an initialization entry point to 
be called first. 

All the routines work by generating a sequence of 48-bit integer values, X„ 
according to the linear congruential formula 

X„+i = (aX„+c)^odm n>0. 
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The parameter m = 2^^; hence 48-bit integer arithmetic is performed. Unless 
lcong48 has been invoked, the multiplier value a and the addend value c are 
given by 

a = 5DEECE66Di6 = 273673163155 8 
c = = 138- 

The value returned by any of the functions drand48, erand4:S, lrand48, 
nrand48, mrand48, or jrand48 is computed by first generating the next 48-bit 
X,- in the sequence. Then the appropriate number of bits, according to the 
type of data item to be returned, are copied from the high-order (leftmost) 
bits of X, and transformed into the returned value. 

The functions drand48, lrand48, and mrand48 store the last 48-bit X,- gen- 
erated in an internal buffer, and must be initialized prior to being invoked. 
The functions erand48, nrand48, and jrand48 require the calling program to 
provide storage for the successive X, values in the array specified as an 
argument when the functions are invoked. These routines do not have to 
be initialized; the calling program must place the desired initial value of X, 
into the array and pass it as an argument. By using different arguments, 
functions erand48, nrand48, and jrand48 allow separate modules of a large 
program to generate several independent streams of pseudo-random 
numbers; i.e., the sequence of numbers in each stream will not depend upon 
how many times the routines have been called to generate numbers for the 
other streams. 

The initializer function srand48 sets the high-order 32 bits of X, to the 32 
bits contained in its argument. The low-order 16 bits of X, are set to the 
arbitrary value 330Ei6. 

The initializer function seed48 sets the value of X, to the 48-bit value speci- 
fied in the argument array. In addition, the previous value of X, is copied 
into a 48-bit internal buffer used only by seed48, and a pointer to this buffer 
is the value returned by seed48. This returned pointer, which can just be 
ignored if not needed, is useful if a program is to be restarted from a given 
point at some future time — use the pointer to get at and store the last X, 
value, and then use this value to reinitialize via seed48 when the program is 
restarted. 

The initialization function lcong48 allows the user to specify the initial X„ 
the multiplier value a, and the addend value c. Argument array elements 
param[0-2] specify X„ param[3-5] specify the multiplier a, and param[6] 
specifies the 16-bit addend c. After lcong48 has been called, a subsequent 
call to either srand48 or seed48 will restore the "standard" multiplier and 
addend values, a and c, specified on the previous page. 

SEE ALSO 

rand(3C). 

NOTES 

The source code for the portable version can be used on computers which 
do not have floating-point arithmetic. In such a situation, functions drand48 
and erand48 are replaced by the two new functions below. 
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long irand48 (m) 
unsigned short m; 

long krand48 (xsubi, m) 
unsigned short xsubi[3], m; 

Functions irand48 and krand48 return non-negative long integers uniformly 
distributed over the interval [0, m-1]. 
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NAME 

dup2 - duplicate an open file descriptor 

SYNOPSIS 

int dup2 (Hides, fildes2) 
int Hides, Hldes2; 

DESCRIPTION 

The fildes argument is a file descriptor referring to an open file, and fildesl 
is a non-negative integer less than NOFILES. dup2 causes fildesl to refer to 
the same file as fildes. If fildesl already referred to an open file, it is closed 
first. 

The dupl function will fail if one or more of the following is true: 
[EBADF] Fildes is not a valid open file descriptor. 

[EMFILE] NOFILES file descriptors are currently open. 

SEE ALSO 

creat(2), close(2), exec{2), fcntl(2), open(2), pipe(2), lockf(3C). 
DIAGNOSTICS 

Upon successful completion a non-negative integer, namely the file descrip- 
tor, is returned. Otherwise, a value of -1 is returned, and errno is set to 
indicate the error. 
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NAME 

ecvt, fcvt, gcvt - convert floating-point number to string 
SYNOPSIS 

char *ecvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, ^decpt, ♦sign; 

char *fcvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, ^sign; 

char *gcvt (value, ndigit, buf) 
double value; 
int ndigit; 
char *buf; 

DESCRIPTION 

The ecvt function converts value to a null-terminated string of ndigit digits 
and returns a pointer thereto. The high-order digit is non-zero, unless the 
value is zero. The low-order digit is rounded. The position of the decimal 
point relative to the beginning of the string is stored indirectly through 
decpt (negative means to the left of the returned digits). The decimal point 
is not included in the returned string. If the sign of the result is negative, 
the word pointed to by sign is non-zero, othervdse it is zero. 

Fcvt is identical to ecvt, except that the correct digit has been rounded for 
printf "%f" (FORTRAN F-format) output of the number of digits specified by 
ndigit. or / 

Gcvt converts the value to a null-terminated string in the array pointed to 
by buf and rehims buf. It attempts to produce ndigit significant digits in 
FORTRAN F-format if possible, otherwise E-format, ready for printing. A 
minus sign, if there is one, or a decimal point vdll be included as part of the 
returned string. Trailing zeros are suppressed. 
SEE ALSO 

printf(3S). 

BUGS 

The values rehimed by ecvt and fcvt point to a single static data array 
whose content is overwritten by each call. 
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NAME 

end, etext, edata - last locations in program 

SYNOPSIS 

extern end; 
extern etext; 
extern edata; 

DESCRIPTION 

These names refer neither to routines nor to locations with interesting con- 
tents. The address of etext is the first address above the program text, edata 
above the initialized data region, and end above the uninitialized data 
region. 

When execution begins, the program break (the first location beyond the 
data) coincides with end, but the program break may be reset by the rou- 
tines of hrk(2), malloc{3C)r standard input/output [stdio(3S)l the profile (-p) 
option of cc(l), and so on. Thus, the current value of the program break 
should be determined by sbrk ((char *)0) [see brk{2)]. 

SEE ALSO 

cc(l), brk(2), malloc(3C), stdio(3S). 
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NAME 

erf, erfc - error function and complementary error function 
SYNOPSIS 

#include <math.h> 

double erf (x) 
double x; 

double erfc (x) 
double x; 

DESCRIPTION 

The erf function returns the error function of x, defined as — fe'^^dt 

erfc, which returns 1.0 - erf(x), is provided because of the extreme loss of 
relative accuracy if erf(x) is called for large x and the result subtracted from 
1.0 (e.g., for x = 5,ll places are lost). 

SEE ALSO 

exp(3M). 



- 1 - 



EXP(3M) 



(C Software Development Set) 



EXP(3M) 



NAME 

exp, log, loglO, pow, sqrt - exponential, logarithm, power, square root func- 
tions 

SYNOPSIS 

#include <math.h> 

double exp (x) 
double x; 

double log (x) 
double x; 

double loglO (x) 
double x; 

double pow (x, y) 
double X, y; 

double sqrt (x) 
double x; 

DESCRIPTION 

The exp function returns e^. 

Log returns the natural logarithm of x. The value of x must be positive. 

LoglO returns the logarithm base ten of x. The value of x must be positive. 

Pow returns 7^ . If a: is zero, y must be positive. If x is negative, y must be 
an integer. 

Sqrt returns the non-negative square root of x. The value of x may not be 
negative. 

SEE ALSO 

hypot(3M), matherr(3M), sinh(3M). 

DIAGNOSTICS 

The exp function returns HUGE v^hen the correct value would overflow, or 
when the correct value would underflow, and sets errno to ERANGE. 

Log and loglO return -HUGE and set errno to EDOM when x is non-positive. 
A message indicating DOMAIN error (or SING error when x is 0) is printed 
on the standard error output. 

Pow returns and sets errno to EDOM when x is and y is non-positive, ojr 
when X is negative and y is not an integer. In these cases a message indi- 
cating DOMAIN error is printed on the standard error output. When the 
correct value for pow would overflow or underflow, pow returns ±HUGE pr 
respectively, and sets errno to ERANGE. 

Sqrt returns and sets errno to EDOM when x is negative. A message indi- 
cating DOMAIN error is printed on the standard error output. 

These error-handling procedures may be changed with the function 
matherr{3M). 
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NAME 

fclose, fflush - close or flush a stream 

SYNOPSIS 

#include <stdio.h> 

int fclose (stream) 
FILE *stream; 

int fflush (stream) 
FILE ♦stream; 

DESCRIPTION 

The fclose function causes any buffered data for the named stream to be 
written out, and the stream to be closed. 

The fclose function is performed automatically for all open files upon calling 
exit{2). 

Fflush causes any buffered data for the named stream to be written to that 
file. The stream remains open. 

SEE ALSO 

close(2), exit(2), fopen(3S), setbuf(3S), stdio(3S). 
DIAGNOSTICS 

These functions return for success and EOF if any error (such as trying to 
write to a file that has not been opened for writing) was detected. 
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NAME 

ferror, feof, clearerr, fileno - stream status inquiries 

SYNOPSIS 

#include <stdio.h> 

int ferror (stream) 
FILE I'Stream; 

int feof (stream) 
FILE ^stream; 

void clearerr (stream) 
FILE ^stream; 

int fileno (stream) 
FILE "cstream; 

DESCRIPTION 

The ferror function returns non-zero when an I/O error has previously 
occurred reading from or writing to the named stream, otherwise zero. 

Feof returns non-zero when EOF has previously been detected reading the 
named input stream, otherwise zero. 

Clearerr resets the error indicator and EOF indicator to zero on the named 
stream . 

Fileno returns the integer file descriptor associated with the named stream; 
see open{2). 

SEE ALSO 

open(2), fopen(3S), stdio(3S). 

NOTES 

All these functions are implemented as macros; they cannot be declared or 
redeclared. 
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NAME 

field - FIELD library routines 
SYNOPSIS 

#include <form.h> 

cc [ flags ] files -Iform -Icurses [ libraries ] 

FIELD * new-field (r, c, frow, fcol, nrow, nbuf) 
int r, c, frow, fcol, nrow, nbuf; 

FIELD ♦ dup-Jield (field, frow, fcol) 
FIELD ♦ field; 
int frow, fcol; 

FIELD * link_field (field, frow, fcol) 
FIELD ♦ field; 
int frow, fcol; 

int free-field (field) 
FIELD * field; 

int field-info (field, rows, cols, frow, fcol, nrow, nbuf) 
FIELD * field; 

int ♦ rows, * cols, * frow, ♦ fcol, ♦ nrow, nbuf; 

int move-field (field, frow, fcol) 
FIELD * field; 
int frow, fcol; 

int set-field-type (field, type, [arg-l, arg-2, ...1) 
FIELD ♦ field; i j/ 

FIELDTYPE * type; 

FIELDTYPE * field-type (field) 
FIELD ♦ field; 

char ♦ field-arg (field) 
FIELD * field; 

int set-field-just (field, justification) 
FIELD * field; 
int justification; 

int field-just (field) 
FIELD ♦ field; 

int set-field-fore (field, fore) 
FIELD * field; 
int fore; 

int field-fore (field) 
FIELD ♦ field; 

int set-field-back (field, back) 
FIELD * field; 
int back; 

int field-back (field) 
FIELD * field; 
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int set_field-pad (field, pad) 
FIELD * field; 
int pad; 

int field-pad (field) 
FIELD * field; 

int set_field_buffer (field, buf, value) 
FIELD * field; 
int buf; 
char * value; 

char ♦ field-buffer (field, buf) 
FIELD * field; 
int buf; 

int set-_field_statU8 (field, status) 
FIELD * field; 
int status; 

int field-status (field) 
FIELD * field; 

int set-field-userptr (field, userptr) 
FIELD * field; 
char * userptr; 

char * field-userptr (field) 
FIELD * field; 

int set-field-opts (field, opts) 
FIELD * field; 
OPTIONS opts; 

int field— opts-on (field, opts) 
FIELD * field; 
OPTIONS opts; 

int field— opts-off (field, opts) 
FIELD * field; 
OPTIONS opts; 

OPTIONS field-opts (field) 
FIELD * field; 

options: 

O-ACTIVE 

O-PUBLIC 

0_EDIT 

O-WRAP 

O-BLANK 

O-AUTOSKIP 

O-NULLOK 

DESCRIPTION 

These FIELD routines run on the AT&T processor line using any terminal 
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supported by cur8es(3X), the low-level ETI library. Once you compile your 
ETI program #includeing the header file form.h, you should link it with 
the form and curses library routines. 

FUNCTIONS 

The following is a list of FIELD routines. For a complete description of each 
routine, see the UNIX System V ETI Programmer's Guide. 

new^eld (r, c, frow, feci, nrow, nbuf) creates a new field with r rows, c 
columns; starting at frow, feci in the subwindow of the form to contain the 
field; with nrow offscreen rows and nbuf additional work buffers. It 
returns a pointer to the created field. In general, you should store these 
field pointers in an array. 

dup^eld (field, frow, fool) duplicates the given field at the named loca- 
tion. 

link-^eld (field, frow, feci) also duplicates the given field at the named 
location. However, unlike dup-JieldO, it shares the field buffers between 
both occurrences of the field and permits the setting of different attributes 
for each field. 

free.^eld (field) frees the storage allocated for the given field, 
field-info (field, rows, cols, frow, fcol, nrow, nbuf) returns the size, posi- 
tion, and other named field characteristics to the locations pointed to by the 
pointer arguments rows, cols, frow, fcol, nrow, and nbuf. 

move-field (field, frow, fcol) moves the disconnected field to the location 
frow, fcol in the form subwindow. 

set_field_type (field, type, [arg_l, arg_2, ...]) associates the given field 
type with field. Certain field types take additional arguments. 
TYPE-ALNUM, for instance, requires one, the minimum width specification 
for the field. ^ 

field-type (field) returns a pointer to the field type of field. 

field-arg (field) returns a pointer to the field arguments associated with the 
field type of field. 

set-field-just (field, justification) sets the justification for the given field 
Justification may be NO-JUSTIFICATION, JUSTIFY_RIGHT 
JUSTIFY-LEFT, or JUSTIFY-CENTER. 

field— just (field) returns the indicator of the justification for the field, 
set-field-fore (field, fore) sets the foreground attribute of field. The fore- 
ground attribute is the low-level ETI visual display attribute used to display 
the field characters. 

field— fore (field) returns the foreground attribute of field, 
set-field-back (field, back) sets the background attribute of field. The 
background attribute is the low-level ETI visual display attribute used to 
display the area immediately surrounding the field characters, 
field— back (field) returns the background attribute of field. 
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set—field— pad (field, pad) sets the pad (blank) character for field, 
field— pad (field) returns the pad character for field. 

set-field— buffer (field, buf, value) sets buffer buf of field to value. 

Buffer stores the displayed value of the field. 

field-buffer (field, buf) returns the value of field buffer buf. 

Every field has an associated status flag that is set whenever the field's 
value (field buffer 0) changes. set_field-status (field, status) sets the 
field's status flag to status, 
field— status (field) returns the status of field. 

Every field has an associated user pointer that you can use to store pertinent 
data. 

set— field— userptr (field, userptr) sets the field's user pointer, 
field— userptr (field) returns the field's user pointer. 

set-field— opts (field, opts) turns on the named options of the field and 
turns off all its remaining options. Options are boolean values. 

field— opts— on (field,opts) turns on the named options. 

field— opts— off (field, opts) turns off the named options. 

field— opts (field) returns the field's options setting. To set options, you can 
apply boolean operators to the value returned by field— optsO and let the 
result be the second argument to set— field— optsO. 

options: 

O-VISIBLE field displayed 

O— ACTIVE field visited during processing 

O— PUBLIC field displayed as data entered 

O— EDIT field can be edited 

O— WRAP words not fitting on field line are wrapped to next line 

O-BLANK whole field erased if first character entered before any 

other character changed 

O— AUTOSKIP moves to start of next field when current field full 

O— NULLOK can leave blank field without validating it 

DIAGNOSTICS 

The following values are returned by one or more routines that return an 
integer. For specific information on which routines return which value, see 
the ETI Programmer's Guide. 

E__OK function returned successfully 

E— CONNECTED object is connected 

E-SYSTEM-ERROR system error 

E-BAD-ARGUMENT argument is incorrect 

E— CURRENT field is current field 

E— POSTED form is posted 
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E_JNVALID_FIELD field is invalid 

E_JVOT_CONNECTED object is not connected 
E_NO_ROOM form does not fit in subwindow 

E_BAD_STATE called from inappropriate routine 

E-.UNKNOWN_.COMMAND 

unknown command was given to the form 
driver 

E— REQUEST__DENIED recognized request failed 
SEE ALSO 

curses(3X), fieldtype(3X), form(3X), item(3X), menu(3X), panel(3X), tam(3X). 
The UNIX System V ETI Programmer's Guide. 
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NAME 

fieldtype - FIELDTYPE library routines 

SYNOPSIS 

#include <form.h> 

cc [ flags ] files -Worm -Icurses [ libraries ] 
typedef int (* PTF-Jnt) 0; 

FIELDTYPE * new-fieldtype (£ield_check, char«-check) 
PTF_int field-check; 
PTF-Jnt char_check; 

int free_-fieldtype(fieldtype); 
FIELDTYPE * fieldtype; 

typedef char * (* PFT_charP) (); 
typedef void (* PFT-void) (); 

int set_fieldtype_arg (fieldtype, mak_arg, cpy_arg, free_arg) 

FIELDTYPE * fieldtype; 

char * mak— arg(ap); 

va-Jist * ap; 

PTF-charP cpy_arg; 

PTF__void free_arg; 

typedef char * (* PFT-charP) (); 

int set_fieldtype-choice (fieldtype, next-choice, prev_choice) 
FIELDTYPE * fieldtype; 
PTF_int next-choice; 
PTF— int prev— choice; 

int next-choice (FIELD * f, char * arg); 
int prev-choice (FIELD * f, char * arg); 

FIELDTYPE * Unk-fieldtyp (typel,type2) 
FIELDTYPE * typel; 
FIELDTYPE * type2; 

DESCRIPTION 

These FIELDTYPE routines run on the AT&T processor line using any ter- 
minal supported by cur8es(3X), the low-level ETI library. Once you compile 
your ETI program #includeing the header file form.h, you should link it 
with the form and curses library routines. 

FUNCTIONS 

The following is a list of FIELDTYPE routines. For a complete description of 
each routine, see the UNIX System V ETI Programmer's Guide. 
new-fieldtype (field-check, char-check) creates a new field type. You 
must write functions field— check, which validates the field value and 
char— check, which validates each character. 

free-fieldtype(fieldtype) frees the space allocated for the given field type. 
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By associating the given function pointers with the field type 
seLJieldtype-arg (fieldtype, mak_arg, cpy-arg, £ree_arg) connects to the 
field type additional arguments necessary for a set_field__type() call Func- 
tion mak-_arg allocates a structure for the field specific parameters to 
seLJield_typeO and returns a pointer to the saved data. Function 
copy_arg duplicates the structure created by make_arg. Function free_are 
frees any storage allocated by make_arg or copy_arg. 

Requests REQ_NEXT_CHOICE and REQ_PREV_CHOICE let the user 
choose the next or previous value of a field type comprising an ordered set 
of values. seLfieldtype-choice (fieldtype, next^choice, prev^choice) 
enables you to implement these requests for the given field type It associ- 
ates with the given field type application-defined functions that return 
pointers to the next or previous choice for the field. 

link_fieldtyp (typel,type2) returns a pointer to the field type built from the 
two given types. The constituent types may be any application-defined or 
ETI-defmed types. 

SEE ALSO 

curses(3X), form(3X), field(3X), panel(3X), menu(3X), item(3x), tam(3X). 
The UNIX System V ETI Programmer's Guide. 
DIAGNOSTICS 

The following values are returned by one or more routines that return an 
IJl^^lt'; specific information on which routines return which value, see 
the ETI Programmer's Guide. 

^— function returned successfully 
E_CONNECTED object is connected 

E_SYSTElVLERROR system error 

E_BAD«ARGUMENT argument is incorrect 

E^CURRENT field is current field 

E_POSTED form is posted 

E JNVALID_FIELD field is invalid 

E^OT^CONNECTED object is not connected 

E_NO«ROOM form does not fit in subwindow 

E_BAD_STATE called from inappropriate routine 

E-.UNKNOWN_COMMAND unknown command was given to the form 

driver 

E-REQUEST-.DENIED recognized request failed 
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NAME 

floor, ceil, fmod, fabs - floor, ceiling, remainder, absolute value functions 

SYNOPSIS 

#include <math.h> 

double floor (x) 
double x; 

double ceil (x) 
double x; 

double fmod (x, y) 
double X, y; 

double fabs (x) 
double x; 

DESCRIPTION 

floor returns the largest integer (as a double-precision number) not greater 
than X. 

ceil returns the smallest integer not less than x, 

fmod returns the floating-point remainder of the division of x by y: x if y is 
zero or if x/y would overflow; otherwise the number / with the same sign 
as X, such that x = iy f for some integer z, and I /! < I y I . 

fobs returns the absolute value of jc, I xl . 

SEE ALSO 

abs(3C). 
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NAME 

fopen, freopen, fdopen - open a stream 
SYNOPSIS 

#include <stdio.h> 

FILE «fopen (filename, type) 
char «filename, *type; 

FILE *freopen (filename, type, stream) 
char ^filename, *type; 
FILE ^stream; 

FILE «fdopen (fildes, type) 
int fildes; 
char *type; 

DESCRIPTION 

The fopen function opens the fUe named by filename and associates a stream 
with It. The fopen function returns a pointer to the FILE structure associated 
with the stream. 

Filename points to a character string that contains the name of the file to be 
opened. 

Type is a character string having one of the following values: 

open for reading 
truncate or create for writing 

append; open for writing at end of file, or create for writ- 
ing 

open for update (reading and writing) 
truncate or create for update 
append; open or create for update at end-of-file 

Freopen substitutes the named file in place of the open stream. The original 
stream is closed, regardless of whether the open ultimately succeeds. Freo- 
pen returns a pointer to the FILE structure associated with stream. 

Freopen is typically used to attach the preopened streams associated with 
stdin, stdout, and stderr to other files. 

Fdopen associates a stream with a file descriptor. File descriptors are 
obtained from open, dup, creat, or pipe{2\ which open files but do not 
return pointers to a FILE structure stream. Streams are necessary input for 
many of the Section 3S library routines. The type of stream must agree 
with the mode of the open file. 

When a file is opened for update, both input and output may be done on 
the resulting stream. However, output may not be directly followed by 
input without an intervening fseek or rewind, and input may not be directly 
foUowed by output without an intervening fseek, rewind, or an input opera- 
tion which encounters end-of-file. 



"w" 
"a" 

"r+ " 
"wH- " 
"a-l-" 
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When a file is opened for append (i.e., when type is "a" or "a+")/ it is 
impossible to overwrite information already in the file. The fseek function 
may be used to reposition the file pointer to any position in the file, but 
when output is written to the file, the current file pointer is disregarded. All 
output is written at the end of the file and causes the file pointer to be repo- 
sitioned at the end of the output. If two separate processes open the same 
file for append, each process may write freely to the file without fear of des- 
troying output being vmtten by the other. The output from the two 
processes vydll be intermixed in the file in the order in which it is vmtten. 

SEE ALSO 

creat(2), dup(2), open(2), pipe(2), fclose(3S), fseek(3S), stdio(3S). 
DIAGNOSTICS 

fopen, fdopen, and freopen return a NULL pointer on failure. 
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NAME 

form - FORM library routines 

SYNOPSIS 

#include <form.h> 

cc [ flags ] files -Iform -Icurses [ libraries ] 

FORM * new-form (fields) 
FIELD fields; 

int free_form (form) 
FORM * form; 

int set_new_page (field, bool) 
FIELD * field; 
int bool; 

int new_page (field) 
FIELD * field; 

int set_form_fields (form, fields) 
FORM * form; 
FIELD ** fields; 

FIELD form_iields (form) 
FORM * form; 

int field_count (form) 
FORM * form; 

int set_form_win (form, window) 
FORM * form; 
WINDOW ♦ window; 

WINDOW * form-win (form) 
FORM * form; 

int seL-form_sub (form, window) 
FORM * form; 
WINDOW ♦ window; 

WINDOW ♦ form-_8ub (form) 
FORM * form; 

int set-current—field (form, field) 
FORM * form; 
FIELD * field; 

FIELD * current-field (form) 
FORM * form; 

int field-index(field) 
FIELD * field; 

int set— form—page (form, page) 
FORM ♦ form; 
int page; 

int form— page (form) 
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FORM * form; 

int scale—form (form, rows, cols) 
FORM * form; 
int * rows, cols; 

typedef void (* PTF_void) (); 

int set_form-Jnit (form, func) 
FORM ♦ form; 
PTF_void func; 

PTF-void form-init (form) 
FORM * form; 

int set_-iornL.term (form, func) 
FORM * form; 
PTF_void func; 

PTF_void form—term (form) 
FORM * form; 

int set— field-Jnit (form, func) 
FORM * form; 
PTF-void func; 

PTF-void field-init (form) 
FORM * form; 

int set— field— term (form, func) 
FORM ♦ form; 
PTF-void func; 

PTF-void field-term (form) 
FORM * form; 

int post— form (form) 
FORM ♦ form; 

int unpost— form (form) 
FORM * form; 

int pos— form— cursor (form) 
FORM * form; 

int form— driver (form, c) 
FORM * form; 
int c; 

int set— form— userptr (form, userptr) 
FORM ♦ form; 
char * userptr; 

char * form— userptr (form) 
FORM * form; 

int set— form— opts (form, opts) 
FORM ♦ form; 
OPTIONS opts; 
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OPTIONS forin_opts (form) 
FORM * form; 

int form_opt8_on (form, opts) 
FORM * form; 
OPTIONS * opts; 

int form_opts_off (form, opts) 
FORM ♦ form; 
OPTIONS * opts; 

DESCRIPTION 

FORM routines run on the AT&T processor line using any terminal sup- 
ported by curses(3X), the low-level ETI library. Once you compile your ETI 
program #includeing the FORM header file form.h, you should link it with 
the form and curses library routines. 

FUNCTIONS 

The following is a list of FORM routines. For a complete description of 
each, see the UNIX System V ETI Programmer's Guide. 

new_form (fields) creates a new form connected to the designated fields 
and returns a pointer to the form. 

free_form (form) disconnects the form from its associated field pointer 
array and deallocates the space for the form. 

set_new.page (fieId,bool) marks the given field to begin a new page of 
the form. 

new— page (field) returns a boolean value indicating whether or not the 
given field begins a new page of the form. 

setL^ornu-fields (form, fields) changes the fields connected to form to 
fields. 

form—fields (form) returns a pointer to the field pointer array connected to 
form. 

field— count (form) returns the number of fields connected to form. 

set- form-win (form, window) sets window as the form window of form. 

form— win (form) returns a pointer to the window associated with form. 

set-form— sub (form, window) sets window as the form subwindow of 
form. 

form— sub (form) returns a pointer to the subwindow associated with form. 

set-current-field (form, field) sets the current field of form to field. 

current-field (form) returns a pointer to the current field of form. 

field-index(field) returns the index in the field pointer array to the given 
field 

set-form— page (form, page) sets the page number of form to page, 
form— page (form) returns the current page number of form. 
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scale-Jorm (form, rows, cols) returns the smallest window size necessary 
for form, rows and cols are pointers to the locations used to return the 
number of rows and columns for the form. 

The workhorse of the forms subsystem, f orm_driver (form, c), checks if the 
character c is a form request or data. If it is a request, the form driver exe- 
cutes the request and reports the result. If it is data (a printable ASCII char- 
acter), it enters the data into the current position in the current field. If it is 
not recognized, the form driver assumes it is an application-defined com- 
mand and returns E_UNKNOWN_COMMAND. 

The following set- functions enable you to establish application routines to 
be executed automatically at initialization and termination points in your 
form application. You need not specify any application-defined initializa- 
tion or termination routines at all, but they may be helpful for displaying 
messages or page numbers and other chores. 

set_form_init (form, func) sets an application-defined initialization func to 
be called when the form is posted and just after a page change. 

form_init (form) returns a pointer to the initialization function, if any, 
called when the form is posted and just after a page change. 

set— form^term (form, func) sets an application-defined func to be called 
when the form is unposted and just before a page change. 

fornL-term (form) returns a pointer to the termination function, if any, 
called when the form is unposted and just before a page change. 

set_field-init (form, func) sets an application-defined func to be called 
when the form is posted and just after the current field changes. 

field_init (form) returns a pointer to the initialization function, if any, 
called when the form is posted and just after the current field changes. 

set— field—term (form, func) sets func to be called when the form is 
unposted and just before the current field changes. 

field— term (form) returns a pointer to the termination function, if any, 
called when the form is unposted and just before the current field changes. 

post— form (form) writes the form in its associated subwindow. 

unpost— form (form) erases the form from its associated subwindow. 

pos— form— cursor (form) moves the form window cursor to the location 
required by the form driver to resume form processing. This is sometimes 
helpful after you write a message or page number. 

Every form has an associated user pointer that you can use to store per- 
tinent data, set— form— userptr (form, userptr) sets the form's user pointer. 

form— userptr (form) returns the form's user pointer. 

set— form— opts (form, opts) turns on the named options for the form and 
turns off all its remaining options. Options are boolean values. Currently, 
there are two form options, 0_NL_OVERLOAD and 0_BS_OVERLOAD. 

form— opts (form) returns the form's options setting. 
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form— optS—on (form, opts) turns on the named options. 
form_opts— off (form, opts) turns off the named options. 
SEE ALSO 

curses(3X), field(3X), fieldtype(3X), item(3x), panel(3X), menu(3X), tam(3X). 
The UNIX System V ETI Programmer's Guide, 
DIAGNOSTICS 

The following values are returned by one or more routines that return an 
integer. For specific information on which routines return which value, see 
the ETI Programmer's Guide. 



E_OK 

E_CONNECTED 

E_SYSTEM_ERROR 

E_BAD_ARGUMENT 

E_CURRENT 

E_POSTED 

E_INVALID_FIELD 

E-JSrOT_CONNECTED 

E_NO_ROOM 

E_B AD-STATE 

E-UNKNOWN_COMMAND 

E_REQUEST_DENIED 



function returned successfully 

object is connected 

system error 

argument is incorrect 

field is current field 

form is posted 

field is invalid 

object is not connected 

form does not fit in subwindow 

called from inappropriate routine 

unknown command was given to the form 
driver 

recognized request failed 
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NAME 

fpgetround, fpsetround, fpgetmask, fpsetmask, fpgetsticky, fpsetsticky - 
IEEE floating point environment control 

SYNOPSIS 



#include <ieeefp.h> 

typedef enum { 

FP_RN=0, 
FP_JIM, 
FP-RP, 
FP_RZ, 
} fp_rnd; 



/* round to nearest */ 

/* round to minus */ 

/* round to plus */ 

/* round to zero (truncate) */ 



fp_rnd fpgetroundO; 

fp_rnd fpsetround(rnd_dir) 
l^_rnd rnd_dir; 

#define fp_except int 

#define FP_X_INV 0x01 /* 

#define FP-JCOFL 0x08 /* 

#define FP_X_UFL 0x10 /* 

#define FP-X-DZ 0x04 /* 

#define FP_X_IMP 0x20 /* 

#define FP-J(_DNML 0x02 /* 

fp_except fpgetmaskO; 



invalid operation exception*/ 
overflow exception*/ 
underflow exception*/ 
divide-by-zero exception*/ 
imprecise (loss of precision)*/ 
denormalization exception */ 



fp_except fpsetmask(mask); 
i^_except mask; 

fp— except fpgetstickyO; 

fp_except fpsetsticky(sticky); 
fi>_except sticky; 

DESCRIPTION 

There are six floating point exceptions: divide-by-zero, overflow, underflow, 
imprecise (inexact) result, denormalization, and invalid operation. When a 
floating point exception occurs, the corresponding sticky bit is set (1), and if 
the mask bit is enabled (1), the trap takes place. These routines let the user 
change the behavior on occurrence of any of these exceptions, as well as 
change the rounding mode for floating point operations. 

fpgetroundQ returns the current rounding mode. 

fpsetroundQ sets the rounding mode and returns the previous rounding 
mode. 



fpgetmaskQ returns the current exception masks. 
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fpsetmaskQ sets the exception masks and returns the previous setting. 
fpgetstickyQ returns the current exception sticky flags. 

fpsetstickyQ sets (clears) the exception sticky flags and returns the previous 
setting. 

The default environment on the Intel 80386 processor family is: 

Rounding mode set to nearest(FP_RN), 

Divide-by-zero, 

Floating point overflow, and 

Invalid operation traps enabled. 

SEE ALSO 

isnan(3C). 

WARNINGS 

fpsetstickyQ modifies all sticky flags. fpsetmaskQ changes all mask bits. 

C requires truncation (round to zero) for floating point to integral conver- 
sions. The current rounding mode has no effect on these conversions. 

CAVEATS 

One must clear the sticky bit to recover from the trap and to proceed. If the 
sticky bit is not cleared before the next floating point instruction is executed, 
a wrong exception type may be signaled. 

For the same reason, when calling fpsetmaskQ the user should make sure 
that the sticky bit corresponding to the exception being enabled is cleared. 
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NAME 

fread, f write - binary input/output 

SYNOPSIS 

#include <stdio.h> 
#include <sy8/types.h> 

int fread (ptr, size, nitems, stream) 
char *ptr; 
int nitems; 
size_t size; 
FILE *8tream; 

int fwrite (ptr, size, nitems, stream) 
char *ptr; 
int nitems; 
size_t size; 
FILE ^stream; 

DESCRIPTION 

The fread function copies, into an array pointed to by ptr, nitems items of 
data from the named input stream, where an item of data is a sequence of 
bytes (not necessarily terminated by a null byte) of length size, fread stops 
appending bytes if an end-of-file or error condition is encountered while 
reading stream, or if nitems items have been read, fread leaves the file 
pointer in stream, if defined, pointing to the byte following the last byte 
read if there is one. fread does not change the contents of stream. 

fwrite appends at most nitems items of data from the array pointed to by ptr 
to the named output stream, fwrite stops appending when it has appended 
nitems items of data or if an error condition is encountered on stream, 
fwrite does not change the contents of the array pointed to by ptr. 

The argument size is typically sizeof(*ptr) where the pseudo-function sizeof 
specifies the length of an item pointed to by ptr. If ptr points to a data type 
other than char, it should be cast into a pointer to char. 

SEE ALSO 

read(2), write(2), fopen(3S), getc{3S), gets{3S), printf(3S), putc(3S), puts(3S), 
scanf(3S), stdio(3S). 

DIAGNOSTICS 

The fread and fwrite functions return the number of items read or written. 
If nitems is non-positive, no characters are read or written, and is returned 
by both fread and fwrite. 
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NAME 

frexp, Idexp, modf - manipulate parts of floating-point numbers 
SYNOPSIS 

double frexp (value, eptr) 
double value; 
int *eptr; 

double Idexp (value, exp) 
double value; 
int exp; 

double modf (value, iptr) 
double value, *iptr; 

DESCRIPTION 

Every non-zero number can be written uniquely as x* 2", where the 
"mantissa" (fraction) x is in the range 0.5 :^ Ijcl < 1.0, and the "exponent" 
n is an integer, frexp returns the mantissa of a double value and stores the 
exponent indirectly in the location pointed to by eptr. If value is zero, both 
results returned by frexp are zero. 

Ldexp returns the quantity value * 2^^^. 

Modf returns the signed fractional part of value and stores the integral part 
indirectly in the location pointed to by iptr. 

DIAGNOSTICS 

If ldexp would cause overflow, ±HUGE (defined in <math.h> ) is returned 

(according to the sign of value), and errno is set to ERANGE. 

If ldexp would cause underflow, zero is returned and errno is set to 

ERANGE. 
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NAME 

fseek, rewind, ftell - reposition a file pointer in a stream 

SYNOPSIS 

#include <8tdio.h> 
#include <unistd.h> 

int fseek (stream, offset, ptrname) 
FILE ♦stream; 
long offset; 
int ptrname; 

void rewind (stream) 
FILE *stream; 

long ftell (stream) 
FILE "fstream; 

DESCRIPTION 

The fseek function sets the position of the next input or output operation on 
the stream. The new position is at the signed distance offset bytes from the 
beginning, from the current position, or from the end of the file, according 
as ptrname has the value 0, 1, or 2, which is defined in the <unistd.h> 
header file as follows: 

Name Description SEEK__SET Set position equal to 

offset bytes. 

SEEK_CUR Set position to current location plus offset. 
SEEK_END Set position to EOF plus offset, 

Rewind{stream) is equivalent to fseek(stream , OL, 0), except that no value is 
returned. 

fseek and rewind undo any effects of ungetc{3S). 

After fseek or rewind, the next operation on a file opened for update may be 
either input or output. 

Vtell returns the offset of the current byte relative to the beginning of the 
file associated with the named stream. 

SEE ALSO 

lseek(2), fopen(3S), popen(3S), stdio(3S), ungetc(3S). 
DIAGNOSTICS 

The fseek function returns non-zero for improper seeks, otherwise zero. An 
improper seek can be, for example, an fseek done on a file that has not been 
opened via fopen; in particular, fseek may not be used on a terminal or on a 
file opened via popen{3S). 

WARNING 

Although on the UNIX system an offset returned by ftell is measured in 
bytes, and it is permissible to seek to positions relative to that offset, porta- 
bility to non-UNIX systems requires that an offset be used by fseek directly. 
Arithmetic may not meaningfully be performed on such an offset, which is 
not necessarily measured in bytes. 
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NAME 

ftw - walk a file tree 

SYNOPSIS 

#include <ftw.h> 

int ftw (path, fn, depth) 
char *psLth; 
int (*fn) ( ); 
int depth; 

DESCRIPTION 

The ftw function recursively descends the directory hierarchy rooted in path. 
For each object in the hierarchy, ftw calls fn, passing it a pointer to a null- 
terminated character string containing the name of the object, a pointer to a 
Stat structure [see stat(2)] containing information about the object, and an 
integer. Possible values of the integer, defined in the <ftw.h> header file, 
are FTW_F for a file, FTW_D for a directory, FTW_DNR for a directory that 
cannot be read, and FTW_NS for an object for which stat could not success- 
fully be executed. If the integer is FTW_DNR, descendants of that directory 
will not be processed. If the integer is FTW_NS, the stat structure will con- 
tain garbage. An example of an object that would cause FTW_NS to be 
passed to fn would be a file in a directory with read but without execute 
(search) permission. 

The ftw function visits a directory before visiting any of its descendants. 
The tree traversal continues until the tree is exhausted, an invocation of fn 
returns a nonzero value, or some error is detected within ftw (such as an 
I/O error). If the tree is exhausted, ftw returns zero. If fn returns a 
nonzero value, ftw stops its tree traversal and returns whatever value was 
returned by fn. If ftw detects an error, it returns -1 and sets the error type 
in ermo. 

The ftw function uses one file descriptor for each level in the tree. The 
depth argument limits the number of file descriptors so used. If depth is 
zero or negative, the effect is the same as if it were 1. Depth must not be 
greater than the number of file descriptors currently available for use. ftw 
will run more quickly if depth is at least as large as the number of levels in 
the tree. 

SEE ALSO 

stat(2), malloc(3C). 

BUGS 

Because ftw is recursive, it is possible for it to terminate with a memory 
fault when applied to very deep file structures. 
CAVEAT 

The ftw function uses malloc to allocate dynamic storage during its opera- 
tion. If ftw is forcibly terminated, such as by longjmp being executed by fn 
or an interrupt routine, ftw will not have a chance to free that storage, so it 
will remain permanently allocated. A safe way to handle interrupts is to 
store the fact that an interrupt has occurred, and arrange to have fn return a 
nonzero value at its next invocation. 
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NAME 

gamma - log gamma function 

SYNOPSIS 

#include <math.h> 

double gamma (x) 
double x; 

extern int signgam; 
DESCRIPTION 

00 

The gamma function returns ln(!r(:c)l), where r(:c) is defined as J 

The sign of r( x) is returned in the external integer signgam . The argument 
X may not be a non-positive integer. 

The following C program fragment might be used to calculate F: 

if ((y = gamma(x)) > LN_MAXDOUBLE) 

error(); 
y = signgam * exp(y); 

where LN-_MAXDOUBLE is the least value that causes exp{3M) to return a 
range error, and is defined in the <values.h> header file. 

SEE ALSO 

exp(3M), matherr(3M), values(5). 

DIAGNOSTICS 

For non-negative integer arguments HUGE is returned, and ermo is set to 
EDOM. A message indicating SING error is printed on the standard error 
output [e.g. gamma (-5.0)]. 

If the correct value would overflow, gamma returns HUGE and sets ermo to 
ERANGE. 

These error-handling procedures may be changed with the function 
matherr{3M). 
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NAME 

getc, getchar, fgetc, getw - get character or word from a stream 

SYNOPSIS 

#include <stdio.h> 

int getc (stream) 
FILE ♦stream; 

int getchar () 

int fgetc (stream) 
FILE ^stream; 

int getw (stream) 
FILE ^stream; 

DESCRIPTION 

The getc function returns the next character (i.e., byte) from the named 
input stream, as an integer. It also moves the file pointer, if defined, ahead 
one character in stream, getchar is defined as getc(stdin) . getc and getchar 
are macros. 

The fgetc function behaves like getc, but is a function rather than a macro. 
Fgetc runs more slowly than getc, but it takes less space per invocation and 
its name can be passed as an argument to a function. 

The getw function returns the next word (i.e., integer) from the named input 
stream, Getw increments the associated file pointer, if defined, to point to 
the next word. The size of a word is the size of an integer and varies from 
machine to machine. Getw assumes no special alignment in the file. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), gets(3S), putc(3S), scanf(3S), 
stdio(3S). 

DIAGNOSTICS 

These functions return the constant EOF at end-of-file or upon an error. 
Because EOF is a valid integer, ferror{3S) should be used to detect getw 
errors. 

WARNING 

If the integer value returned by getc, getchar, or fgetc is stored into a charac- 
ter variable and then compared against the integer constant EOF, the com- 
parison may never succeed, because sign-extension of a character on widen- 
ing to integer is machine-dependent. 

CAVEATS 

Because it is implemented as a macro, getc evaluates a stream argument 
more than once. In particular, getc(*f++) does not work sensibly. Fgetc 
should be used instead. 

Because of possible differences in word length and byte ordering, files writ- 
ten using putw are machine-dependent, and may not be read using getw on 
a different processor. 
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NAME 

getcwd - get path name of current working directory 

SYNOPSIS 

char ♦getcwd (buf, size) 
char *buf; 
int size; 

DESCRIPTION 

The getcwd function returns a pointer to the current directory path name. 
The value of size must be at least tv^o greater than the length of the path 
name to be returned. 

If huf is a NULL pointer, getcwd vsrill obtain size bytes of space using 
malloc{3C), In this case, the pointer returned by getcwd may be used as the 
argument in a subsequent call to free. 

The function is implemented by using popen(3S) to pipe the output of the 
pwd(l) command into the specified string space. 

EXAMPLE 

void exit(), perror{); 



if ((cwd = getcwd{(char *)NULL, 64)) == NULL) { 

perror( "pvs^d" ); 
exit(2); 

} 

printf( " %s\n " , cwd); 

SEE ALSO 

malloc(3C), popen(3S). 

pwd(l) in the User's /System Administrator's Reference Manual. 
DIAGNOSTICS 

Returns NULL with errno set if size is not large enough, or if an error occurs 
in a lower-level function. 

[EINVAL] If size is zero. 

[EBIANGE] If size is not large enough to hold the path name. 
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NAME 

getenv - return value for environment name 

SYNOPSIS 

char ♦getenv (name) 
char mame; 

DESCRIPTION 

The getenv function searches the environment list [see environ{5)] for a 
string of the form name = value and returns a pointer to the value in the 
current environment if such a string is present, otherwise a NULL pointer. 

SEE ALSO 

exec(2), putenv(3C), environ(5). 
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NAME 

getgrent, getgrgid, getgmam, setgrent, endgrent, fgetgrent - get group file 
entry 

SYNOPSIS 

#include <grp.h> 

struct group ♦getgrent ( ) 

struct group *getgrgid (gid) 
int gid; 

struct group «getgrnam (name) 
char «name; 

void setgrent ( ) 

void endgrent ( ) 

struct group *fgetgrent (f) 
FILE *f; 

DESCRIPTION 

The getgrent, getgrgid, and getgmam functions each return pointers to an 
object with the following structure containing the broken-out fields of a line 
in the /etc/group file. Each line contains a "group" structure, defined in 
the <grp.h> header file. 

struct group { 

char *gr_jiame; /* the name of the group */ 

char *gr_passwd; /* the encrypted group password */ 

int gr— gid; /* the numerical group ID */ 

char **gr-_mem; /* vector of pointers to member names */ 

}; 

The getgrent function when first called returns a pointer to the first group 
structure in the file; thereafter, it returns a pointer to the next group struc- 
ture in the file; so, successive calls may be used to search the entire file. 
Getgrgid searches from the beginning of the file until a numerical group ID 
matching gid is found and returns a pointer to the particular structure in 
which it was found. Getgmam searches from the beginning of the file until 
a group name matching name is found and returns a pointer to the particu- 
lar structure in which it was found. If an end-of-file or an error is encoun- 
tered on reading, these functions return a NULL pointer. 

A call to setgrent has the effect of rewinding the group file to allow repeated 
searches. Endgrent may be called to close the group file when processing is 
complete. 

Fgetgrent returns a pointer to the next group structure in the stream /, which 
matches the format of /etc/group. 

FILES 

/etc/group 
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SEE ALSO 

getlogin(3C), getpwent(3C), group(4). 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 
WARNING 

The above routines use <8tdio.h>, which causes them to increase the size 
of programs, not otherwise using standard I/O, more than might be 
expected. 

CAVEAT 

All information is contained in a static area, so it must be copied if it is to 
be saved. 
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NAME 

gethz - return the frequency of the system clock in ticks per second 

SYNOPSIS 

int gethzO ; 

DESCRIPTION 

gethz returns the frequency of the system clock in ticks per second. 

SEE ALSO 

environ(5) 

WARNING 

In the current implementation, gethz searches the environment list [see 
environ(5)] for a string of the form HZ=val , and returns va\. 
If HZ is not defined in the environment, or if HZ cannot be interpreted as a 
numeric integer, gethz returns 0. 

CAVEAT 

The implementation of gethz may change. 
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NAME 

getlogin - get login name 

SYNOPSIS 

char «getlogin ( ); 

DESCRIPTION 

The getlogin function returns a pointer to the login name as found in 
/etc/utmp. It may be used in conjunction with getpwnam to locate the 
correct password file entry when the same user ID is shared by several login 
names. 

If getlogin is called within a process that is not attached to a terminal, it 
returns a NULL pointer. The correct procedure for determining the login 
name is to call cuserid, or to call getlogin and if it fails, to call getpwuid. 

FILES 

/etc/utmp 
SEE ALSO 

cuserid(3S), getgrent(3C), getpwent(3C), utmp(4). 
DIAGNOSTICS 

Returns the NULL pointer if name is not found. 
CAVEAT 

The return values point to static data whose content is overwritten by each 
call. 
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NAME 

getopt - get option letter from argument vector 

SYNOPSIS 

int getopt (argc, argv, optstring) 
int argc; 

char **argv, *opstring; 

extern char *optarg; 
extern int optind, opterr; 

DESCRIPTION 

The getopt function returns the next option letter in argv that matches a 
letter in optstring. It supports all the rules of the command syntax standard 
[see mfro(l)]. So all new commands will adhere to the command syntax 
standard, they should use getopts{l) or getopt {3C) to parse positional 
parameters and check for options that are legal for that command. 

optstring must contain the option letters the command using getopt vsdll 
recognize; if a letter is followed by a colon, the option is expected to have 
an argument, or group of arguments, which must be separated from it by 
white space. 

optarg is set to point to the start of the option-argument on return from 
getopt. 

getopt places in optind the argv index of the next argument to be processed, 
optind is external and is initialized to 1 before the first call to getopt. 

When all options have been processed (i.e., up to the first non-option argu- 
ment), getopt returns -1. The special option " — " may be used to delimit 
the end of the options; when it is encountered, -1 will be returned, and 
" — " vdll be skipped. 

The follov\dng rules comprise the System V standard for command-line syn- 
tax: 

RULE 1 Command names must be between two and nine charac- . 



ters. 



RULE 2 



RULE 3 



RULE 5 



RULE 4 



RULE 7 



RULE 6 



RULE 8 



Command names must include lowercase letters and digits 
only. 

Option names must be a single character in length. 

All options must be delimited by the - character. 

Options with no arguments may be grouped behind one 
delimiter. 

The first option-argument following an option must be pre- 
ceded by white space. 

Option arguments cannot be optional. 

Groups of option arguments foUovydng an option must be 
separated by commas or separated by white space and 
quoted. 
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RULE 9 All options must precede operands on the command line. 

RULE 10 The characters — may be used to delimit the end of the 

options. 

RULE 11 The order of options relative to one another should not 

matter. 

RULE 12 The order of operands may matter and position-related 

interpretations should be determined on a command- 
specific basis. 

RULE 13 The - character preceded and followed by white space 

should be used only to mean standard input. 

The function getopt is the command-line parser that will enforce the rules of 
this command syntax standard. 

EXAMPLE 

The following code fragment shows how one might process the arguments 
for a command that can take the mutually exclusive options a and b, and 
the option o, which requires an option-argument: 

main ( argc , argv) 
int argc ; 
char **argv; 
{ 

int c ; 

extern char *optarg; 
extern int optind; 

while ((c = getopt(argc, argv, "abo:")) != -1) 
switch (c) { 



case 



case 



case 



} 



if (bflg) 

errf lg++ ; 

else 

af lg++ ; 
break ; 
V: 

if (aflg) 

errf lg++ ; 

else 

bproc( ); 
break ; 



ofile = 

break; 

'?': 

errf lg++ ; 



optarg ; 



if (errflg) { 

( void ) f print f ( stderr , 



•usage : 



") ; 
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exit (2); 



} 

for ( 



; optind < argc ; optind++) { 
if ( access ( argv[optind] , 4)) { 



} 

SEE ALSO 

getopts(l), intro(l) in the User's /System Administrator's Reference Manual. 
DIAGNOSTICS 

getopt prints an error message on standard error and returns a question 
mark (?) when it encounters an option letter not included in optstring or no 
option-argument after an option that expects one. This error message may 
be disabled by setting opterr to 0. 



Although the following command syntax rule [see intro{l)] relaxations are 
permitted under the current implementation, they should not be used 
because they may not be supported in future releases of the system. As in 
the EXAMPLE section above, a and b are options, and the option o requires 
an option-argument: 

cmd -aboxxx file (Rule 5 violation: options with 



Changing the value of the variable optind or calling getopt with different 
values of argv may lead to unexpected results. 



WARNING 



option-arguments must not be 
grouped with other options) 



cmd -ab -oxxx file 



(Rule 6 violation: there must be 
white space after an option that 
takes an option-argument) 
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NAME 

getpass - read a password 

SYNOPSIS 

char «getpass (prompt) 
char ♦prompt; 

DESCRIPTION 

The getpass function reads up to a new-line or EOF from the file /dev/tty 
after prompting on the standard error output with the null-terminated string 
prompt and disabling echoing. A pointer is returned to a null-terminated 
string of at most 8 characters. If /dev/tty cannot be opened, a NULL 
pointer is returned. An interrupt will terminate input and send an interrupt 
signal to the calling program before returning. 

FILES 

/dev/tty 
WARNING 

The above routine uses <stdio.h>, which causes it to increase the size of 
programs not otherwise using standard I/O more than might be expected. 
CAVEAT 

The return value points to static data whose content is overwritten bv each 
call. ^ 
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NAME 

getpw - get name from UID 

SYNOPSIS 

int getpw (uid, buf) 
int uid; 
char *buf; 

DESCRIPTION 

The getpw function searches the password file for a user ID number that 
equals uid, copies the line of the password file in which uid was found into 
the array pointed to by buf, and returns 0. getpw returns non-zero if uid 
cannot be found. 

This routine is included only for compatibility with prior systems and 
should not be used; see getpwent (3C) for routines to use instead. 

FILES 

/etc/passwd 

SEE ALSO 

getpwent(3C), passwd(4). 

DIAGNOSTICS 

The getpw function returns non-zero on error. 

WARNING 

The above routine uses <stdio.h>, which causes it to increase, more than 
might be expected, the size of programs not otherwise using standard I/O. 
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NAME 

getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent - get pass- 
word file entry 

SYNOPSIS 

#include <pwd.h> 

struct passwd *getpwent ( ) 

struct passwd ♦getpwuid (uid) 
int uid; 

struct passwd ♦getpwnam (name) 
char «name; 

void setpwent ( ) 

void endpwent ( ) 

struct passwd ^fgetpwent (f) 
FILE *f; 

DESCRIPTION 

The getpwent, getpwuid, and getpwnam functions each returns a pointer to 
an object with the following structure containing the broken-out fields of a 
line in the /etc/passwd file. Each line in the file contains a "passwd" 
structure, declared in the <pwd,h> header file: 

struct passwd { 



char 


*pw__name; 


char 


*pw_passwd; 


int 


pw_uid; 


int 


pw_gid; 


char 


*pw_age; 


char 


*pw_comment; 


char 


*pw__gecos; 


char 


*pw_dir; 


char 


*pw_5hell; 



This structure is declared in <pwd.h> so it is not necessary to redeclare it. 
The fields have meanings described in passwd{^). 

The getpwent function when first called, returns a pointer to the first passwd 
structure in the file; thereafter, it returns a pointer to the next passwd struc- 
ture in the file; so successive calls can be used to search the entire file. 
Getpwuid searches from the beginning of the file until a numerical user ID 
matching uid is found and returns a pointer to the particular structure in 
which it was found. Getpwnam searches from the beginning of the file until 
a login name matching name is found, and returns a pointer to the particu- 
lar structure in which it was found. If an end-of-file or an error is encoun- 
tered on reading, these functions return a NULL pointer. 

A call to setpwent has the effect of rewinding the password file to allow 
repeated searches. Endpwent may be called to close the password file when 
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processing is complete. 

Fgetpwent returns a pointer to the next passwd structure in the stream /, 
which matches the format of /etc/passwd. 

FILES 

/etc/passwd 

SEE ALSO 

getlogin(3C), getgrent(3C), passwd(4). 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

WARNING 

The above routines use <stdio.h>, which causes them to increase the size 
of programs, not otherwise using standard I/O, more than might be 
expected. 

CAVEAT 

All information is contained in a static area, so it must be copied if it is to 
be saved. 
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NAME 

gets, fgets - get a string from a stream 

SYNOPSIS 

#mclude <8tdio.h> 

char ♦gets (s) 
char ^s; 

char ♦^ets (s, n, stream) 
char «s; 
int n; 

FILE ♦stream; 
DESCRIPTION 

The gets function reads characters from the standard input stream, stdin, 
into the array pointed to by s, until a new-line character is read or an end- 
of-file condition is encountered. The new-line character is discarded and 
the string is terminated with a null character. 

The fgets function reads characters from the stream into the array pointed to 
by s, until n-1 characters are read, or a new-line character is read and 
transferred to s, or an end-of-file condition is encountered. The string is 
then terminated with a null character. 

SEE ALSO 

ferror(3S), fopen(3S), fread(3S), getc(3S), scanf(3S), stdio(3S). 
DIAGNOSTICS 

If end-of-file is encountered and no characters have been read, no characters 
are transferred to s and a NULL pointer is returned. If a read error occurs, 
such as trying to use these functions on a file that has not been opened for 
reading, a NULL pointer is returned. Otherwise s is returned. 
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NAME 

getut: getutent, getutid, getutline, pututline, setutent, endutent, utmpname - 
access utmp file entry 

SYNOPSIS 

#include <utmp.h> 

struct utmp '('getutent ( ) 

struct utmp "^getutid (id) 
struct utmp *id; 

struct utmp ^getutline (line) 
struct utmp *line; 

void pututline (utmp) 
struct utmp 'I'utmp; 

void setutent ( ) 

void endutent ( ) 

void utmpname (file) 
char ^Hle; 

DESCRIPTION 

The getutent, getutid, and getutline functions each return a pointer to a 
structure of the following type: 

struct utmp { 

char ut_user[8]; /* User login name */ 

char ut_id[4]; /* /etc/inittab id (usually line #) */ 

char ut_line[12]; /* device name (console, Inxx) */ 

short ut_pid; /* process id */ 

short ut_t)q?e; /* type of entry */ 

struct exit—Status { 

short e— termination; /* Process termination status */ 
short e_exit; /* Process exit status */ 

} ut_exit; /* The exit status of a process 

* marked as DEAD_PROCESS. */ 
time_t ut_time; /* time entry was made */ 

}; 

The getutent function reads in the next entry from a utmp -like file. If the 
file is not already open, it opens it. If it reaches the end of the file, it fails. 

The getutid function searches forward from the current point in the utmp 
file until it finds an entry with a ut—type matching id->ut^type if the type 
specified is RUN_LVL, BOOT_TIME, OLD_TIME or NEW_TIME. If the type 
specified in id is INIT_PROCESS, LOGIN_PROCESS, USER-PROCESS or 
DEAD—PROCESS, then getutid will return a pointer to the first entry whose 
type is one of these four and whose ut—id field matches id->ut—id. If the 
end of file is reached without a match, it fails. 
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The getutline function searches forward from the current point in the utmp 
file until it finds an entry of the type LOGIN-PROCESS or USER_PROCESS, 
which also has a ut-Jine string matching the line->utJiine string. If the 
end of file is reached without a match, it fails. 

Pututline writes out the supplied utmp structure into the utmp file. It uses 
getutid to search forward for the proper place if it finds that it is not already 
at the proper place. It is expected that normally the user of pututline will 
have searched for the proper entry using one of the getut routines. If so, 
pututline will not search. If pututline does not find a matching slot for the 
new entry, it will add a new entry to the end of the file. 

Setutent resets the input stream to the beginning of the file. This should be 
done before each search for a new entry if it is desired that the entire file be 
examined. 

Endutent closes the currently open file. 

Utmpname allows the user to change the name of the file examined, from 
/etc/utmp to any other file. It is most often expected that this other file 
will be /etc/wtmp. If the file does not exist, this will not be apparent until 
the first attempt to reference the file is made. Utmpname does not open the 
file. It just closes the old file if it is currently open and saves the new file 
name. 

FILES 

/etc/utmp 
/etc/wtmp 

SEE ALSO 

ttyslot(3C), utmp{4). 

DIAGNOSTICS 

A NULL pointer is returned upon failure to read, whether for permissions or 
having reached the end of file, or upon failure to write. 

NOTES 

The most current entry is saved in a static structure. Multiple accesses 
require that it be copied before further accesses are made. Each call to 
either getutid or getutline sees the routine examine the static structure before 
performing more I/O. If the contents of the static structure match what it is 
searching for, it looks no further. For this reason, to use getutline to search 
for multiple occurrences, it would be necessary to zero out the static after 
each success, or getutline would just return the same pointer over and over 
again. There is one exception to the rule about removing the structure 
before further reads are done. The implicit read done by pututline (if it 
finds that it is not already at the correct place in the file) will not hurt the 
contents of the static structure returned by the getutent, getutid, or getutline 
routines, if the user has just modified those contents and passed the pointer 
back to pututline. 

These routines use buffered standard I/O for input, but pututline uses an 
unbuffered non-standard write to avoid race conditions between processes 
trying to modify the utmp and wtmp files. 
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NAME 

hsearch, hcreate, hdestroy - manage hash search tables 

SYNOPSIS 

#include <search.h> 

ENTRY *hsearch (item, action) 
ENTRY item; 
ACTION action; 

int hcreate (nel) 
unsigned nel; 

void hdestroy ( ) 

DESCRIPTION 

The hsearch function is a hash-table search routine generalized from Knuth 
(6.4) Algorithm D. It returns a pointer into a hash table indicating the loca- 
tion at which an entry can be found. Item is a structure of type ENTRY 
(defined in the <search.h> header file) containing two pointers: item.key 
points to the comparison key, and item.data points to any other data to be 
associated with that key. (Pointers to types other than character should be 
cast to pointer-to-character.) Action is a member of an enumeration type 
ACTION indicating the disposition of the entry if it cannot be found in the 
table. ENTER indicates that the item should be inserted in the table at an 
appropriate point. FIND indicates that no entry should be made. Unsuc- 
cessful resolution is indicated by the return of a NULL pointer. 

Hcreate allocates sufficient space for the table and must be called before 
hsearch is used. Nel is an estimate of the maximum number of entries that 
the table will contain. This number may be adjusted upward by the algo- 
rithm in order to obtain certain mathematically favorable circumstances. 

Hdestroy destroys the search table and may be followed by another call to 
hcreate, 

EXAMPLE 

The following example will read in strings followed by two numbers and 
store them in a hash table, discarding duplicates. It will then read in strings 
and find the matching entry in the hash table and print it out. 

#include <stdio.h> 
#include <search.h> 

struct info { /* this is the info stored in the table ♦/ 

int age, room; /* other than the key. */ 

}; 

#define num_empl 5000 /* # of elements in search table ♦/ 

main( ) 
{ 

/• space to store strings ♦/ 
char string_space [NUM_EMPL*20 ] ; 
/♦ space to store employee info ♦/ 
struct info inf o_space [num_empl ] ; 



- 1 - 



HSEARCH(3C) 



(C Software Development Set) 



HSEARCH(3C) 



/* next avail space in string_space */ 
char *str_jptr = string_space ; 
/♦ next avail space in info_space */ 
struct info *info_ptr = info_space; 
ENTRY item, *f ouncl_iteni, ♦hsearchC ); 
/♦ name to look for in table */ 
char name_to_f ind [30]; 
int i = ; 

/* create table */ 

( void ) her eate ( num_empl ) ; 

while (scanf ( "%s36d%d" , str_ptr, fitinf o_ptr->age , 

Siinf o_ptr— >room) 1= EOF && i + + < num_empl) { 

/* put info in structure, and structure in item */ 

item. key = str_ptr; 

item. data = (char *)info_ptr; 

str_ptr += strlen( str_ptr ) + 1; 

inf o_ptr++ ; 

/♦ put item into table */ 
(void) hsearch( item, enter); 

} 
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/* access table ♦/ 

item. key = name_to_f ind ; 

while (scanf("%s", item. key) 1= EOF) { 

if ((found_item = hsearch ( item , find)) != null) { 
/* if item is in the table ♦/ 

( void) printf ( "found %s , age = %d, room = %d\n" , 
f ound_item->key , 

({struct info *) f ound_item— >data ) — >age , 
((struct info *) f ound_item— >data )— >room) ; 

} else { 

(void)printf ( "no such employee %s\n" , 
name_to_f ind ) 

} 



} 



NOTES 



SEE ALSO 

bsearch(3C), lsearch(3C), malloc(3C), malloc(3X), string(3C), tsearch{3C). 
DIAGNOSTICS 

The hsearch function returns a NULL pointer if either the action is FIND and 
the item could not be found, or the action is ENTER and the table is full. 
Hcreate returns zero if it cannot allocate sufficient space for the table. 

The hsearch function uses open addressing with a multiplicative hash func- 
tion. However, its source code has many other options available which the 
user may select by compiling the hsearch source with the following symbols 
defined to the preprocessor: 

DIV Use the remainder modulo table size as the hash function 
instead of the multiplicative algorithm. 

USCR Use a User-Supplied Comparison Routine for ascertaining 
table membership. The routine should be named hcom- 
par and should behave in a mannner similar to strcmp 
[see string{3C)]. 

CHAINED Use a linked list to resolve collisions. If this option is 
selected, the following other options become available. 

START Place new entries at the beginning of the 
linked list (default is at the end). 

SORTUP Keep the linked list sorted by key in 
ascending order. 

SORTDOWN Keep the linked list sorted by key in des- 
cending order. 

Additionally, there are preprocessor flags for obtaining debugging printout 
(-DDEBUG) and for including a test driver in the calling routine 
(-DDRIVER). The source code should be consulted for further details. 
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WARNING 

hsearch and hcreate use malloc(3C) to allocate space. 
CAVEAT 

Only one hash search table may be active at any given time. 
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NAME 

hypot - Euclidean distance function 

SYNOPSIS 

#include <math.h> 

double hypoi (x, y) 
double X, y; 

DESCRIPTION 

hypot returns 

sqrt(x * X + y * y), 

taking precautions against unwarranted overflows. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

When the correct value would overflow, hypot returns HUGE and sets errno 
to ERANGE. 

These error-handling procedures may be changed with the function 
inatherr(3M). 
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NAME 

isnan: isnand, isnanf - test for floating point NaN (Not-A-Number) 

SYNOPSIS 

#mclude <ieeefp.h> 

int isnand (dsrc) 
double dsrc; 

int isnanf (fsrc) 
float fsrc; 

DESCRIPTION 

The isnand and isnanf functions return true (1) if the argument dsrc or fsrc is 
a NaN; otherwise they return false (0). 

Neither routine generates any exception, even for signaling NaNs. 

isnanfO is implemented as a macro included in <ieeefp.h>. 

SEE ALSO 

fpgetround(3C). 
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NAME 

item - CRT item routines 

SYNOPSIS 

#include <menu.h> 

cc [ flags ] files -Imenu -Icurses [ libraries ] 
ITEM *new_item(n, d) 
ITEM * item; 
char *n, *d; 

int free_item(i) 
ITEM * i; 

char *iteixi-iiame(i) 
ITEM * i; 

char *item_description(i) 
ITEM ♦ i; 

int set-item—optsG, o) 
ITEM ♦ item; 
OPTIONS o; 

OPTIONS item_opts(i) 
ITEM * i; 

int itenu.opts— on (item, opts) 
ITEM * item; 
OPTIONS opts; 

int item_opts— off (item, opts) 
ITEM * item; 
OPTIONS opts; 

int set_item_value(i, c) 
ITEM ♦ item; 
int *c; 

int item_value(i) 
ITEM * item; 

int set—item— userptr(i, n) 
ITEM * item; 
char *n; 

char *item-.userptr(i) 
ITEM * i; 

int item_count(m) 
MENU *m; 

int item— visible(i) 
ITEM * item; 



DESCRIPTION 

These routines allow you to create, display, and access items. Menus can be 
displayed on any display device supported by the low-level Extended 
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Terminal Interface (ETI) library curses{3X), Once you compile your program 
includeing the ITEM header file menu.h, you should link it with the ITEM 
and curses library routines. 

FUNCTIONS 

new-Jtem(n, d) creates a new item with name n and description d. It 
returns a pointer to the new item. In general, you should store these item 
field pointers in an array. 

free_itemO frees the storage allocated for the given item. Once an item is 
freed, you can no longer connect it to a menu. 

itein.-name(i) returns a pointer to the given item's name. 

item_description(i) returns a pointer to the given item's description. 

sei-item_opts(i, o) turns on the named option(s) for the item and turns off 
its remaining options, if any. Options are boolean values. Currently, there 
is one item option 0--SELECTABLE which enables your end-user to select 
the item. The initial current default is to have O— SELECTABLE on for 
every item. 

iteiiL_opts(i) returns the given item's option(s) setting. To set options, you 
can apply boolean operators to the value returned by itein_opts() and let 
the result be the second argument to set—itenu-optsO. 

itein_optS-.on (item, opts) turns on the named options for the item. 

item_optS— off (item, opts) turns off the named options for the item. 

Unlike single-valued menus, multi-valued menus enable your end-user to 
select one or more items from a menu. set_item— value(i, c) sets the given 
item's select value— TRUE (selected) or FALSE (not selected). To make a 
menu multi-valued, you use set_menu_opts() or menu_opts-.off0 to turn 
off option O—ONEVALUE. setJ[tem_value() may be used only with 
multi-valued menus. 

item-.value(i) returns the select value of the given item, either TRUE 
(selected) or FALSE (unselected). 

Every item has an associated user pointer that you can use to store pertinent 
information. set_item^userptr(i, n) sets the item's user pointer. 

item_userptr(i) returns the item's user pointer. 

item_count(m) returns the number of items in the given menu. 

A menu item is visible if it currently appears in the subwindow of the 
posted menu to which it is connected. If an item is visible, item_visible(i) 
returns TRUE. If not, it returns FALSE. 

SEE ALSO 

curses(3X), field(3X), fieldtype(3X), form(3X), menu(3X), panel(3X), tam(3X). 
The UNIX System V ETI Programmer's Guide. 
DIAGNOSTICS 

The following values are returned by one or more routines that return an 
integer. For specific information on which routine returns which value, see 
the ETI Programmer's Guide. 
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E_OK 

E-_SYSTEM_ERROR 
E_BAD_A.RGUMENT 

E_POSTED 
E-CONNECTED 

E_BAD_STATE 
E_NO-ROOM 
E_NOT__POSTED 
E_UNKNOWN_COMMAND 

E-JNO-JMATCH 
E_NOT_SELECTABLE 
E-NOT_CONNECTED 
E_JIEQUEST_DENIED 



routine returned normally 
system error 

an incorrect argument was passed to the 
routine 

menu is already posted 

one or more items are connected to another 
menu 

routine called from an inappropriate routine 

menu does not fit within its subwindow 

menu has not yet been posted 

unrecognizable request was given to the 
driver 

no match occurred 

item cannot be selected 

no items are associated with the menu 

menu driver could not process the request 
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NAME 

13tol, ltol3 - convert betv^een 3-byte integers and long integers 

SYNOPSIS 

void 13tol dp, qp, n) 
long *lp; 
char *q>; 
int n; 

void ltol3 (q>, Ip, n) 
char *cp; 
long *lp; 
int n; 

DESCRIPTION 

The l3tol function converts a list of n three-byte integers packed into a char- 
acter string pointed to by cp into a list of long integers pointed to by Ip. 

LtolS performs the reverse conversion from long integers (Ip) to three-byte 
integers (cp). 

These functions are useful for file-system maintenance v^here the block 
numbers are three bytes long. 

SEE ALSO 

fs(4). 

CAVEAT 

Because of possible differences in byte ordering, the numerical values of the 
long integers are machine-dependent. 
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NAME 

Idahread - read the archive header of a member of an archive file 

SYNOPSIS 

#include <stdio.h> 
#include <ar.h> 
#mclude <filehdr.h> 
#include <ldfcn.h> 

int Idahread (Idptr, arhead) 
LDFILE *ldptr; 
ARCHDR «arhead; 

DESCRIPTION 

If TYPEildptr) is the archive file magic number, Idahread reads the archive 
header of the common object file currently associated with Idptr into the 
area of memory beginning at arhead. 

Idahread returns SUCCESS or FAILURE. Idahread will fail if TYFEQdptr) does 
not represent an archive file, or if it cannot read the archive header. 

The program must be loaded with the object file access routine library 
Iibld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4), ar(4). 
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NAME 

Idclose, Idaclose - close a common object file 

SYNOPSIS 

#include <8tdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 



int Idclose (Idptr) 
LDFILE *ldptr; 

int Idaclose (Idptr) 
LDFILE *ldptr; 

DESCRIPTION 

The ldopen{3X) and Idclose functions are designed to provide uniform access 
to both simple object files and object files that are members of archive files. 
Thus an archive of common object files can be processed as if it were a 
series of simple common object files. 

If TyFEddptr) does not represent an archive file, Idclose will close the file 
and free the memory allocated to the LDFILE structure associated with Idptr. 
If TYFEildptr) is the magic number of an archive file, and if there are any 
more files in the archive, Idclose will reinitialize OFFSET(ldptr) to the file 
address of the next archive member and return FAILURE. The LDFILE struc- 
ture is prepared for a subsequent ldopen(3X). In all other cases, Idclose 
returns SUCCESS. 

Idaclose closes the file and frees the memory allocated to the LDFILE struc- 
ture associated with Idptr regardless of the value of TYFEfldptr). Idaclose 
always rehims SUCCESS. The function is often used in conjunction with 
Idaopen . 

The program must be loaded with the object file access routine library 
libld.a. 

SEE ALSO 

fclose(3S), ldopen(3X), ldfcn(4). 
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NAME 

Idfhread - read the file header of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int Idfhread (Idptr, filehead) 
LDFILE *ldptr; 
FILHDR «mehead; 

DESCRIPTION 

The Idfhread function reads the file header of the common object file 
currently associated with Idptr into the area of memory beginning at file- 
head, 

Idfhread returns SUCCESS or FAILURE, Idfhread will fail if it cannot read the 
file header. 

In most cases the use of Idfhread can be avoided by using the macro 
HEADERildptr) defined in ldfcn.h [see Idfcn (4)]. The information in any 
field, fieldname, of the file header may be accessed using 
HEADER(ldptr).fieldname. 

The program must be loaded with the object file access routine library 
libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4). 
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NAME 

Idgetname - retrieve symbol name for common object file symbol table 
entry 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <syms.h> 
#include <ld£cn.h> 

char ^Idgetname (Idptr, symbol) 
LDFILE *ldptr; 
SYMENT ^symbol; 

DESCRIPTION 

The Idgetname function returns a pointer to the name associated with sym- 
bol as a string. The string is contained in a static buffer local to Idgetname 
that is overwritten by each call to Idgetname, and therefore must be copied 
by the caller if the name is to be saved. 

The Idgetname function can be used to retrieve names from object files 
without any backward compatibility problems. The Idgetname function will 
return NULL (defined in stdio.h) for an object file if the name cannot be 
retrieved. This situation can occur: 

if the "string table" cannot be found, 

if not enough memory can be allocated for the string table, 

if the string table appears not to be a string table (for example, if an 
auxiliary entry is handed to Idgetname that looks like a reference to 
a name in a nonexistent string table), or 

if the name's offset into the string table is past the end of the string 
table. 

Typically, Idgetname will be called immediately after a successful call to 
Idtbread to retrieve the name associated with the symbol table entry filled 
by Idtbread. 

The program must be loaded with the object file access routine librarv 
libld.a. ^ 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldtbseek(3X), ldfcn(4). 
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NAME 

Idlread, Idlinit, Idlitem - manipulate line number entries of a common object 
file function 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <linenum.h> 
#include <ldfcn.h> 



int Idlreadddptr, fcnindx, linenum, linent) 

LDFILE *ldptr; 

long fcnindx; 

unsigned short linenum; 

LINENO *linent; 

int Idlinitddptr, fcnindx) 
LDFILE *ldptr; 
long fcnindx; 

int Idlitemddptr, linenum, linent) 
LDFILE *ldptr; 
unsigned short linenum; 
LINENO *linent; 

DESCRIPTION 

The Idlread function searches the line number entries of the common object 
file currently associated with Idptr, The Idlread function begins its search 
with the line number entry for the beginning of a function and confines its 
search to the line numbers associated with a single function. The function 
is identified by fcnindx, the index of its entry in the object file symbol table. 
The Idlread function reads the entry with the smallest line number equal to 
or greater than linenum into the memory beginning at linent. 

The Idlinit and Idlitem functions together perform exactly the same function 
as Idlread. After an initial call to Idlread or Idlinit, Idlitem may be used to 
retrieve a series of line number entries associated with a single function. 
Ldlinit simply locates the line number entries for the function identified by 
fcnindx. Idlitem finds and reads the entry with the smallest line number 
equal to or greater than linenum into the memory beginning at linent. 

The Idlread, Idlinit, and Idlitem functions each return either SUCCESS or 
FAILURE. Idlread will fail if there are no line number entries in the object 
file, if fcnindx does not index a function entry in the symbol table, or if it 
finds no line number equal to or greater than linenum. Ldlinit will fail if 
there are no line number entries in the object file or if fcnindx does not 
index a function entry in the s)nnbol table. Ldlitem will fail if it finds no 
line number equal to or greater than linenum . 

The programs must be loaded with the object file access routine library 
Ubld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbindex(3X), ldfcn(4). 
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NAME 

Idlseek, Idnlseek - seek to line number entries of a section of a common 
object file 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <ldfcii.h> 

int Idlseek (Idptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 

int Idnlseek (Idptr, sectname) 
LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

The Idlseek function seeks to the line number entries of the section specified 
by sectindx of the common object file currently associated with Idptr. 

The Idnlseek function seeks to the line number entries of the section speci- 
fied by sectname. 

The Idlseek and Idnlseek functions return SUCCESS or FAILURE. Idlseek will 
fail if sectindx is greater than the number of sections in the object file; 
Idnlseek will fail if there is no section name corresponding with *sectname. 
Either function will fail if the specified section has no line number entries or 
if it cannot seek to the specified line number entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library 
libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 



- 1 - 



LDOHSEEK(3X) 



(C Software Development Set) LDOHSEEK(3X) 



NAME 

Idohseek - seek to the optional file header of a common object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int Idohseek (Idptr) 
LDFaE *ldptr; 

DESCRIPTION 

The Idohseek function seeks to the optional file header of the common object 
file currently associated with Idptr. 

The Idohseek function returns SUCCESS or FAILURE. Idohseek will fail if the 
object file has no optional header or if it cannot seek to the optional header. 

The program must be loaded with the object file access routine library 
libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfhread(3X), ldfcn(4). 
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NAME 

Idopen, Idaopen - open a common object file for reading 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#include <ldfcn.h> 

LDFILE «ldopen (filename, Idptr) 
char ^filename; 
LDFILE *ldptr; 

LDFILE ♦Idaopen (filename, oldptr) 
char ^filename; 
LDFILE *oldptr; 

DESCRIPTION 

The Idopen and ldclose(3X) functions are designed to provide uniform 
access to both simple object files and object files that are members of 
archive files. Thus an archive of common object files can be processed as if 
it were a series of simple common object files. 

If Idptr has the value NULL, then Idopen will open filename and allocate and 
initialize the LDFILE structure, and return a pointer to the structure to the 
calling program. 

If Idptr is valid and if TYFEQdptr) is the archive magic number, Idopen will 
reinitialize the LDFILE structure for the next archive member of filename. 

The Idopen and ldclose{3X) functions are designed to work in concert. 
Ldclose vdll return FAILURE only when TyFE{ldptr) is the archive magic 
number and there is another file in the archive to be processed. Only then 
should Idopen be called with the current value of Idptr. In all other cases, in 
particular whenever a new filename is opened, Idopen should be called v^th 
a NULL Idptr argument. 

The following is a prototype for the use of Idopen and ldclose {3X). 

/♦ for each filename to be processed */ 

Idptr = null; 

do 

{ 

if ( (Idptr = ldopen( filename , Idptr)) 1= null ) 
{ 

/♦ check magic number */ 
/♦ process the file */ 

} 

} while ( ldclose ( Idptr ) == failure ); 

If the value of oldptr is not NULL, Idaopen will open filename anew and allo- 
cate and initialize a new LDFILE structure, copying the TYPE, OFFSET, and 
HEADER fields from oldptr, Idaopen returns a pointer to the new LDFILE 
structure. This new pointer is independent of the old pointer, oldptr. The 
two pointers may be used concurrently to read separate parts of the object 
file. For example, one pointer may be used to step sequentially through the 
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relocation information, while the other is used to read indexed symbol table 
entries. 

Both Idopen and Idaopen open filename for reading. Both functions return 
NULL if filename cannot be opened, or if memory for the LDFILE structure 
cannot be allocated. A successful open does not ensure that the given file is 
a common object file or an archived object file. 

The program must be loaded with the object file access routine library 
libld.a. 

SEE ALSO 

fopen(3S), ldclose(3X), ldfcn(4). 
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NAME 

Idrseek, Idnrseek - seek to relocation entries of a section of a common 
object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int Idrseek (Idptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 

int Idnrseek (Idptr, sectname) 
LDFILE *ldptr; 
char «sectname; 

DESCRIPTION 

The Idrseek function seeks to the relocation entries of the section specified 
by sectindx of the common object file currently associated with Idptr. 

The Idnrseek function seeks to the relocation entries of the section specified 
by sectname. 

The Idrseek and Idnrseek functions return SUCCESS or FAILURE. Idrseek will 
fail if sectindx is greater than the number of sections in the object file; 
Idnrseek will fail if there is no section name corresponding with sectname. 
Either function will fail if the specified section has no relocation entries or if 
it cannot seek to the specified relocation entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library 
libld.a. ^ 

SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

Idshread, Idnshread - read an indexed/r\amed section header of a common 
object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <scnhdr.h> 

#include <ldfcn.h> 

int Idshread (Idptr, sectindx, secthead) 
LDFILE *ldptr; 
unsigned short sectindx; 
SCNHDR *secthead; 

int Idnshread (Idptr, sectname, secthead) 
LDFILE *ldptr; 
char ^sectname; 
SCNHDR *secthead; 

DESCRIPTION 

The Idshread function reads the section header specified by sectindx of the 
common object file currently associated with Idptr into the area of memory 
beginning at secthead. 

The Idnshread function reads the section header specified by sectname into 
the area of memory beginning at secthead. 

The Idshread and Idnshread functions return SUCCESS or FAILURE. Idshread 
will fail if sectindx is greater than the number of sections in the object file; 
Idnshread will fail if there is no section name corresponding with sectname. 
Either function will fail if it cannot read the specified section header. 

Note that the first section header has an index of one. 

The program must be loaded with the object file access routine library 
libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4). 
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NAME 

Idsseek, Idnsseek - seek to an indexed/named section of a common object 
file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int Idsseek (Idptr, sectindx) 
LDFILE *ldptr; 
unsigned short sectindx; 

int Idnsseek (Idptr, sectname) 
LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

The Idsseek function seeks to the section specified by sectindx of the com- 
mon object file currently associated with Idptr. 

The Idnsseek function seeks to the section specified by sectname. 

The Idsseek and Idnsseek functions return SUCCESS or FAILURE. Idsseek will 
fail if sectindx is greater than the number of sections in the object file; 
Idnsseek will fail if there is no section name corresponding with sectname. 
Either function will fail if there is no section data for the specified section or 
if it cannot seek to the specified section. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library 
libld.a. ^ 

SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

Idtbindex - compute the index of a symbol table entry of a common object 
file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <syms.h> 

#include <ldfcn.h> 

long Idtbindex (Idptr) 
LDFILE *ldptr; 

DESCRIPTION 

The Idtbindex function returns the (long) index of the symbol table entry at 
the current position of the common object file associated with Idptr. 

The index returned by Idtbindex may be used in subsequent calls to 
ldtbread(3X). However, since Idtbindex returns the index of the symbol table 
entry that begins at the current position of the object file, if Idtbindex is 
called immediately after a particular symbol table entry has been read, it 
will return the index of the next entry. 

The Idtbindex function will fail if there are no sjonbols in the object file, or if 
the object file is not positioned at the beginning of a symbol table entry. 

Note that the first symbol in the symbol table has an index of zero. 

The program must be loaded with the object file access routine library 
Ubld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldtbseek(3X), ldfcn{4). 
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NAME 

Idtbread - read an indexed symbol table entry of a common object file 

SYNOPSIS 

#include <stdio.h> 
#include <jfilehdr.h> 
#include <syms.h> 
#include <ldfcn.h> 

int Idtbread (Idptr, symindex, symbol) 
LDFILE *ldptr; 
long symindex; 
SYMENT ^symbol; 

DESCRIPTION 

The Idtbread function reads the symbol table entry specified by symindex of 
the common object file currently associated with Idptr into the area of 
memory beginning at symbol. 

The Idtbread function returns SUCCESS or FAILURE. Idtbread will fail if sym- 
index is greater than or equal to the number of symbols in the object file, or 
if it cannot read the specified symbol table entry. 

Note that the first symbol in the symbol table has an index of zero. 

The program must be loaded with the object file access routine library 
libld.a. 

SEE ALSO 

ldclose(3X), ldopen(3X), ldtbseek(3X), ldgetname(3X), ldfcn(4). 
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NAME 

Idtbseek - seek to the symbol table of a common object file 

SYNOPSIS 

#include <stdio.h> 
#include <filehdr.h> 
#mclude <ldfcn.h> 

int Idtbseek (Idptr) 
LDFILE *ldptr; 

DESCRIPTION 

The Idtbseek function seeks to the symbol table of the common object file 
currently associated with Idptr. 

The Idtbseek function returns SUCCESS or FAILURE. Idtbseek will fail if the 
symbol table has been stripped from the object file, or if it cannot seek to 
the symbol table. 

The program must be loaded with the object file access routine library 
libld.a. 



SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldfcn(4). 



- 1 - 



LIBWINDOWS(3X) (C Software Development Set) LIBWINDOWS(3X) 



NAME 

libwindows - windowing terminal function library 
SYNOPSIS 

cc [flag ...] file ... -Iwindows [library ...] 

int cntlfd, fd 

int chan 

int origiii-_x, origin_y, corner—x, corner_y 

char *command 

cntlfd = openagent ( ) 

chan = New (cntlfd, origin_x, origin_y, corner_x, corner— y) 

chan = Newlayer (cntlfd, origin— x, origin_y, corner—x, corner__y) 

fd = openchan (chan) 

Runlayer (chan, command) 

Current (cntlfd, chan) 

Delete (cntlfd, chan) 

Top (cntlfd, chan) 

Bottom (cntlfd, chan) 

Move (cntlfd, chan, origin_x, origin_.y) 

Reshape (cntlfd, chan, origin— x, origin— y, corner— x, corner— y) 
Exit (cntlfd) 
DESCRIPTION 

This library of routines enables a program running on a host UNIX system 
to perform windowing terminal functions [see layers(l)]. 

The openagentO routine opens the control channel of the xt{7) channel 
group to which the calling process belongs. Upon successful completion, 
openagent( ) returns a file descriptor, cntlfd, that can be passed to any of the 
other libwindows routines except openchan() and Runlayer(). [cntlfd can 
also be passed to c/ose(2).] Otherwise, the value -1 is returned. 

The New( ) routine creates a new layer with a separate shell. The origin-jc, 
origin^y, comer-X, and comer^y arguments are the coordinates of the layer 
rectangle. If all the coordinate arguments are 0, the user must define the 
layer's rectangle interactively. The layer appears on top of any overlapping 
layers. The layer is not made current (i.e., the keyboard is not attached to 
the new layer). Upon successful completion, New() returns the xt(7) chan- 
nel number associated with the layer. Otherwise, the value -1 is returned. 

The NewlayerO routine creates a new layer without executing a separate 
shell. Otherwise it is identical to New( ), described above. 

The openchan() routine opens the channel argument chan which is 
obtained from the New( ) or Newlayer( ) routine. Upon successful comple- 
tion, openchanO returns a file descriptor that can be used as input to 
write(2) or close(2). Otherwise, the value -1 is returned. 
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The Runlayer() routine runs the specified command in the layer associated 
with the channel argument chart. Any processes currently attached to this 
layer will be killed, and the new process will have the environment of the 
layers(l) process. 

The Current() routine makes the layer associated with the channel argu- 
ment chan current (i.e., attached to the keyboard). 

The Delete( ) routine deletes the layer associated with the channel argument 
chan and kills all host processes associated with the layer. 

The TopO routine makes the layer associated with the channel argument 
chan appear on top of all overlapping layers. 

The Bottom() routine puts the layer associated with the channel argument 
chan under all overlapping layers. 

The Move() routine moves the layer associated with the channel argument 
chan from its current screen location to a new screen location at the origin 
point {origin-jc, origin— y). The size and contents of the layer are main- 
tained. 

The Reshape( ) routine reshapes the layer associated with the channel argu- 
ment chan. The arguments origins, origin— y, comer— x, and comer— y are 
the new coordinates of the layer rectangle. If all the coordinate arguments 
are 0, the user is allowed to define the layer's rectangle interactively. 

The Exit() routine causes the layers(l) program to exit, killing all processes 
associated with it. 

RETURN VALUE 

Upon successful completion, Runlayer(), Current(), Delete(), Top(), Bot- 
tom(), Move(), Reshape(), and Exit() return a 0, while openagent(), 
New(), Newlayer(), and openchan() return values as described above 
under each routine. If an error occurs, -1 is returned. 

FILES 

/usr/lib/libwindows.a windowing terminal function library 

SEE ALSO 

close(2), jagent(5), write(2). 

layers(l), xt(7) in the User's/System Administrator's Reference Manual, 

NOTE 

The values of layer rectangle coordinates are dependent on the type of ter- 
minal. This dependency affects the routines that pass layer rectangle coor- 
dinates: Move( ), New( ), Newlayer( ), and Reshape( ). Some terminals will 
expect these numbers to be passed as character positions (bytes); others will 
expect the information to be in pixels (bits). 

For example, for the AT&T TELETYPE 5620 DMD terminal, New(), 
Newlayer(), and Reshape() take minimum values of 8 (pixels) for origin— x 
and origin— y and maximum values of 792 (pixels) for comer— x and 1016 
(pixels) for comer— y. In addition, the minimum layer size is 28 by 28 pixels 
and the maximum layer size is 784 by 1008 pixels. 
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NAME 

lockf - record locking on files 

SYNOPSIS 

#include <unistd.h> 

int lockf (fildes, function, size) 
long size; 

int fildes, function; 
DESCRIPTION 

The lockf command will allow sections of a file to be locked; (advisory or 
mandatory write locks are used depending on the mode bits of the file [see 
chmod{2)]). Locking calls from other processes which attempt to lock the 
locked file section will either return an error value or be put to sleep until 
the resource becomes unlocked. All the locks for a process are removed 
when the process terminates. [See fcntl{2) for more information about 
record locking.] 

Fildes is an open file descriptor. The file descriptor must have 0_WRONLY 
or 0_RDWR permission in order to establish a lock with this function call. 

Function is a control value which specifies the action to be taken. The per- 
missible values for function are defined in <unistd.h> as follows: 

#define F_ULOCK /* Unlock a previously locked section */ 

#define F_LOCK 1 /* Lock a section for exclusive use */ 

#define F_TLOCK 2 /* Test and lock a section for exclusive use */ 

#define F_TEST 3 /* Test section for other processes locks */ 



All other values of function are reserved for future extensions and will result 
in an error return if not implemented. 

F_TEST is used to detect if a lock by another process is present on the speci- 
fied section. F_LOCK and F_TLOCK both lock a section of a file if the sec- 
tion is available. F-_ULOCK removes locks from a section of the file. 

Size is the number of contiguous bytes to be locked or unlocked. The sec- 
tion to be locked starts at the current offset in the file and extends forward 
for a positive size and backward for a negative size (the preceding bytes up 
to but not including the current offset). If size is zero, the section from the 
current offset through the largest file offset is locked (i.e., from the current 
offset through the present or any future end-of-file). An area need not be 
allocated to the file in order to be locked as such locks may exist past the 
end-of-file. 

The sections locked with F_LOCK or F_TLOCK may, in whole or in part, 
contain or be contained by a previously locked section for the same process. 
When this occurs, or if adjacent sections occur, the sections are combined 
into a single section. If the request requires that a new element be added to 
the table of active locks and this table is already full, an error is returned, 
and the new section is not locked. 
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F_LOCK and F_TLOCK requests differ only by the action taken if the 
resource is not available. F_LOCK will cause the calling process to sleep 
until the resource is available. F_TLOCK will cause the function to return a 
-1 and set ermo to [EACCES] if the section is already locked by another pro- 
cess. 

F_-ULOCK requests may, in whole or in part, release one or more locked sec- 
tions controlled by the process. When sections are not fully released, the 
remaining sections are still locked by the process. Releasing the center sec- 
tion of a locked section requires an additional element in the table of active 
locks. If this table is full, an [EDEADLK] error is returned, and the requested 
section is not released. 

A potential for deadlock occurs if a process controlling a locked resource is 
put to sleep by accessing another process's locked resource. Thus calls to 
lockf or fcntl scan for a deadlock prior to sleeping on a locked resource. An 
error return is made if sleeping on the locked resource would cause a 
deadlock. 

Sleeping on a resource is interrupted with any signal. The alarm{2) com- 
mand may be used to provide a timeout facility in applications which 
require this facility. 

The lockf utility will fail if one or more of the following is true: 
[EBADF] 

Fildes is not a valid open descriptor. 
[EACCES] 

Cmd is F_TLOCK or F_TEST and the section is already locked by 
another process. 

[EDEADLK] 

Cmd is F_LOCK and a deadlock would occur. Also the cmd is either 
F_LOCK, F_TLOCK, or F_ULOCK and the number of entries in the 
lock table would exceed the number allocated on the system. 

[ECOMM] 

Fildes is on a remote machine and the link to that machine is no 
longer active. 

SEE ALSO 

chmod(2), close(2), creat(2), fcntl(2), intro(2), open(2), read(2), write(2). 
DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 

WARNINGS 

Unexpected results may occur in processes that do buffering in the user 
address space. The process may later read/write data which is/ was locked. 
The standard I/O package is the most common source of unexpected buffer- 
ing. 

Because in the future the variable errno will be set to EAGAIN rather than 
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EACCES when a section of a file is already locked by another process, port- 
able application programs should expect and test for either value. 
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NAME 

logname - return login name of user 

SYNOPSIS 

char ♦logname( ) 

DESCRIPTION 

The logname function returns a pointer to the null-terminated login name; it 
extracts the LOGNAME environment variable from the user's environment. 

This routine is kept in /lib/libPW.a. 

FILES 

/etc/profile 

SEE ALSO 

getenv(3C), profile(4), environ(5). 

env(l), login(l) in the User's /System Administrator's Reference Manual 
CAVEATS 

The return values point to static data whose content is overwritten by each 
call. 

This method of determining a login name is subject to forgery. 
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NAME 

Isearch, Ifind - linear search and update 

SYNOPSIS 

#include <stdio.h> 
#include <search.h> 

char ♦Isearch ((char *)key, (char *)h3Lse, nelp, sizeof(i'key), compar) 
unsigned "cnelp; 
int (♦comparX ); 

char *lfind ((char *)key, (char *)bsLse, nelp, sizeof('i'key), compar) 
unsigned *nelp; 
int (♦compar)( ); 

DESCRIPTION 

The Isearch function is a linear search routine generalized from Knuth (6.1) 
Algorithm S. It returns a pointer into a table indicating where a datum may 
be found. If the datum does not occur, it is added at the end of the table. 
Key points to the datum to be sought in the table. Base points to the first 
element in the table. Nelp points to an integer containing the current 
number of elements in the table. The integer is incremented if the datum is 
added to the table. Compar is the name of the comparison function which 
the user must supply (strcmp, for example). It is called with two arguments 
that point to the elements being compared. The function must return zero if 
the elements are equal and non-zero otherwise. 

Lfind is the same as Isearch except that if the datum is not found, it is not 
added to the table. Instead, a NULL pointer is returned. 

EXAMPLE 

This fragment will read in less than TABSIZE strings of length less than 
ELSIZE and store them in a table, eliminating duplicates. 

#include <stdio.h> 
#include <search.h> 

#define tabsize 50 
#de£ine elsize 120 

char line[ELSiZE] , tab [ tabsize ][ elsize ] , *lsearch( ); 
unsigned nel = 0; 
int strcmp ( ) ; 

while (fgets(line, elsize, stdin) != null &&. 

nel < TABSIZE) 

(void) lsearch( line , (char ♦)tab, &nel, 
ELSIZE, strcmp); 

SEE ALSO 

bsearch(3C), hsearch(3C), string(3C), tsearch(3C). 



- 1 - 



LSEARCH(3C) 



(C Software Development Set) 



LSEARCH(3C) 



DIAGNOSTICS 

If the searched-for datum is found, both Isearch and Ifind return a pointer to 
it. Otherwise, Ifind returns NULL and Isearch returns a pointer to the newly 
added element. 

NOTES 

The pointers to the key and the element at the base of the table should be 
of type pointer-to-element, and cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data 
may be contained in the elements in addition to the values being compared. 

Although declared as type pointer-to-character, the value returned should 
be cast into type pointer-to-element. 

BUGS 

Undefined results can occur if there is not enough room in the table to add 
a new item. 
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NAME 

malloc, free, realloc, calloc - main memory allocator 

SYNOPSIS 

char ♦malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char ^realloc (ptr, size) 
char *ptr; 
unsigned size; 

char I'calloc (nelem, elsize) 
unsigned nelem, elsize; 

DESCRIPTION 

The malloc and free functions provide a simple, general-purpose, memory 
allocation package. The malloc function returns a pointer to a block of at 
least size bytes suitably aligned for any use. 

The argument to free is a pointer to a block previously allocated by malloc; 
after free is performed this space is made available for further allocation, but 
its contents are left undisturbed. 

Undefined results will occur if the space assigned by malloc is overrun or if 
some random number is handed to free. 

The malloc function allocates the first big enough, contiguous reach of free 
space found in a circular search from the last block allocated or freed, 
coalescing adjacent free blocks as it searches. It calls sbrk [see brk{2)] to get 
more memory from the system when there is no suitable space already free. 

Realloc changes the size of the block pointed to by ptr to size bytes and 
returns a pointer to the (possibly moved) block. The contents will be 
unchanged up to the lesser of the new and old sizes. If no free block of size 
bytes is available in the storage arena, then realloc will ask malloc to enlarge 
the arena by size bytes and will then move the data to the new space. 

Realloc also works if ptr points to a block freed since the last call of malloc, 
realloc, or calloc; thus sequences of free, malloc, and realloc can exploit the 
search strategy of malloc to do storage compaction. 

Calloc allocates space for an array of nelem elements of size elsize. The 
space is initialized to zeros. 

Each of the allocation routines returns a pointer to space suitably aligned 
(after possible pointer coercion) for storage of any type of object. 

SEE ALSO 

brk(2), malloc(3X). 

DIAGNOSTICS 

The malloc, realloc and calloc functions return a NULL pointer if there is no 
available memory, or if the arena has been detectably corrupted by storing 
outside the bounds of a block. When this happens the block pointed to by 
ptr may be destroyed. 
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NOTES 

Search time increases when many objects have been allocated; that is, if a 
program allocates but never frees, then each successive allocation takes 
longer. For an alternate, more flexible implementation, see malloc{3X). 
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NAME 

malloc, free, realloc, calloc, mallopt, mallinfo - fast main memory allocator 
SYNOPSIS 

#include <malloc.h> 

char ^malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char *realloc (ptr, size) 
char *ptr; 
unsigned size; 

char ♦calloc (nelem, elsize) 
unsigned nelem, elsize; 

int mallopt (cmd, value) 
int cmd, value; 

struct mallinfo mallinfoO 

DESCRIPTION 

The malloc and free functions provide a simple general-purpose memory 
allocation package, which runs considerably faster than the malloc{3C) pack- 
age. It is found in the library "malloc" and is loaded if the option "-Imal- 
loc" is used with cc(l) or ld{l). 

The malloc function returns a pointer to a block of at least size bytes suit- 
ably aligned for any use. 

The argument to free is a pointer to a block previously allocated by malloc; 
after free is performed, this space is made available for further allocation, 
and its contents have been destroyed. But see mallopt below for a way to 
change this behavior. 

Undefined results will occur if the space assigned by malloc is overrun or if 
some random number is handed to free. 

Realloc changes the size of the block pointed to by ptr to size bytes and 
returns a pointer to the (possibly moved) block. The contents will be 
unchanged up to the lesser of the new and old sizes. 

Calloc allocates space for an array of nelem elements of size elsize. The 
space is initialized to zeros. 

Mallopt provides for control over the allocation algorithm. The available 
values for cmd are: 

M_MXFAST Set maxfast to value. The algorithm allocates all blocks 
below the size of maxfast in large groups and then doles 
them out very quickly. The default value for maxfast is 24. 

M_NLBLKS Set numlblks to value. The above mentioned "large groups" 
each contain numlblks blocks. Numlblks must be greater 
than 0. The default value for numlblks is 100. 
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M_GRAIN Set grain to value. The sizes of all blocks smaller than max- 
fast are considered to be rounded up to the nearest multiple 
of grain. Grain must be greater than 0. The default value 
of grain is the smallest number of bytes which will allow 
alignment of any data type. Value will be rounded up to a 
multiple of the default when grain is set. 

M_KEEP Preserve data in a freed block until the next malloc, realloc, 

or calloc. This option is provided only for compatibility 
with the old version of malloc and is not recommended. 

These values are defined in the <malloc.h> header file. 

Mallopt may be called repeatedly, but may not be called after the first small 

block is allocated. 

Mallinfo provides instrumentation describing space usage. It returns the 
structure: 

struct mallinfo { 
int arena; 
int ordblks; 
int smblks; 
int hblkhd; 
int hblks; 
int usmblks; 
int fsmblks; 
int uordblks; 
int fordblks; 
int keepcost; 



/* 
/* 
/* 
/* 
/* 
/• 
/* 
/* 
/* 
/* 
/* 



total space in arena */ 
number of ordinary blocks */ 
number of small blocks */ 
space in holding block headers */ 
number of holding blocks */ 
space in small blocks in use */ 
space in free small blocks */ 
space in ordinary blocks in use */ 
space in free ordinary blocks */ 
space penalty if keep option */ 
is used */ 



} 

This structure is defined in the <malloc.h> header file. 

Each of the allocation routines rehims a pointer to space suitably aligned 

(after possible pointer coercion) for storage of any type of object. 

SEE ALSO 

brk(2), malloc(3C). 

DIAGNOSTICS ^ ^ 

The malloc, realloc, and calloc functions return a NULL pomter if there is not 
enough available memory. When realloc returns NULL, the block pointed to 
by ptr is left intact. If mallopt is called after any allocation or if cmd or 
value are invalid, non-zero is returned. Otherwise, it returns zero. 

WARNINGS 

This package usually uses more data space than malloc{3C). 
The code size is also bigger than malloc{3C). 

Note that unlike malloc(3C), this package does not preserve the contents of 
a block when it is freed, unless the M_KEEP option of mallopt is used. 
Undocumented features of malloc{3C) have not been duplicated. 
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NAME 

matherr - error-handling function 

SYNOPSIS 

#include <math.h> 

int matherr (x) 
struct exception *x; 

DESCRIPTION 

The matherr function is invoked by functions in the Math Library when 
errors are detected. Users may define their own procedures for handling 
errors by including a function named matherr in their programs. The math- 
err function must be of the form described above. When an error occurs, a 
pointer to the exception structure x will be passed to the user-supplied 
matherr function. This structure, which is defined in the <math.h> header 
file, is as follows: 

struct exception { 
int t)^e; 
char *name; 

double argl, arg2, retval; 

}' 

The element type is an integer describing the type of error that has 
occurred, from the foUov^ng list of constants (defined in the header file): 

DOMAIN argument domain error 
SING argument singularity 

OVERFLOW overflow range error 
UNDERFLOW underflow range error 
TLOSS total loss of significance 

PLOSS partial loss of significance 

The element name points to a string containing the name of the function 
that incurred the error. The variables argl and argl are the arguments with 
which the function was invoked. Retval is set to the default value that will 
be returned by the function unless the user's matherr sets it to a different 
value. 

If the user's matherr function returns non-zero, no error message will be 
printed, and ermo will not be set. 

If matherr is not supplied by the user, the default error-handling procedures, 
described vydth the math functions involved, will be invoked upon error. 
These procedures are also summarized in the table below. In every case, 
ermo is set to EDOM or ERANGE and the program continues. 
EXAMPLE 

#include <math.h> 
int 

matherr ( x ) 

register struct exception *x; 
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{ 

switch (x->type) { 
case domain: 

/* change sqrt to return sqrt(-argl), not */ 
if ( 1 strcmp(x->name , "sqrt")) { 

x->retval = sqrt ( — x— >arg 1 ) ; 

return (0); /* print message and set errno */ 

> 

case sing: 

/* all other domain or sing errors, print message and abort 
f printf { stderr , "domain error in %s\n" , x->name); 
abort { ); 
case PLOSs: 

/* print detailed error message */ 

f printf ( stderr , "loss of significance in %s{%g) = %g\n" , 

x->name, x->arg1, x->retval); 
return ( 1 ) ; /* take no other action ♦/ 



} 

return (0); /* all other errors, execute default procedure */ 

} 



DEFAULT ERROR HANDLING PROCEDURES 




Types 


of Errors 






type 


DOMAIN 


SING 


OVERFLOW 


UNDERFLOW 


TLOSS 


PLOSS 


ermo 


EDOM 


EDOM 


ERANGE 


ERANGE 


ERANGE 


ERANGE 


BESSEL: 










M, 


* 


vO, vl, yn (arg ^ 0) 


M, -H 












EXP: 






H 









LOG, LOGIO: 














fare < 0) 


M, -H 












(are = 0) 




M, -H 










POW: 






±H 











M, 












** non-pos 














SQRT: 


M, 












GAMMA: 




M,H 


H 








HYPOT: 






H 








SINH: 






±H 








COSH: 






H 








SIN, COS, TAN: - 








M, 


* 




ASIN, ACOS, ATAN2: M, 















ABBREVIATIONS: * As much as possible of the value is returned. 



M Message is printed (EDOM error). 

H HUGE is returned. 

-H -HUGE is returned. 

± H HUGE or -HUGE is returned. 

is returned. 
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NAME 

memory: memccpy, memchr, memcmp, memcpy, memset - memory opera- 
tions 

SYNOPSIS 

#include <memory.h> 

char ♦memccpy (si, s2, c, n) 
char *sl, *s2; 
int c, n; 

char ♦memchr (s, c, n) 
char ^s; 
int c, n; 

int memcmp (si, s2, n) 
char *sl, ♦s2; 
int n; 

char «memcpy (si, s2, n) 
char *sl, *s2; 
int n; 

char *memset (s, c, n) 
char *s; 
int c, n; 

DESCRIPTION 

These functions operate as efficiently as possible on memory areas (arrays 
of characters bounded by a count, not terminated by a null character). They 
do not check for the overflow of any receiving memory area. 

Memccpy copies characters from memory area s2 into si, stopping after the 
first occurrence of character c has been copied, or after n characters have 
been copied, whichever comes first. It returns a pointer to the character 
after the copy of c in si, or a NULL pointer if c was not found in the first n 
characters of s2. 

Memchr returns a pointer to the first occurrence of character c in the first n 
characters of memory area s, or a NULL pointer if c does not occur. 

Memcmp compares its arguments, looking at the first n characters only, and 
returns an integer less than, equal to, or greater than 0, according as si is 
lexicographically less than, equal to, or greater than s2. 

Memcpy copies n characters from memory area s2 to si. It returns si. 

Memset sets the first n characters in memory area s to the value of character 
c. It returns s. 

For user convenience, all these functions are declared in the optional 
<memory.h> header file. 
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CAVEATS 

Memcmp is implemented by using the most natural character comparison on 
the machine. Thus the sign of the value returned when one of the charac- 
ters has its high order bit set is not the same in all implementations and 
should not be relied upon. 

Character movement is performed differently in different implementations. 
Thus overlapping moves may yield surprises. 
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NAME 

menu - CRT menu routines 

SYNOPSIS 

#include <menu.h> 

cc [ flags ] files -Imenu -Icurses [ libraries ] 

MENU ♦new— menu(ip) 
ITEM ip; 

int free— menu(m) 
MENU *m; 

int set_menii_items(m,i) 
MENU * m; 
ITEM ** i; 

ITEM ** meniLj[tems(m) 
MENU * m; 

int set_menu_format(m, c, r) 
MENU *m; 
int c, r; 

void menu— format(m, rp, cp) 
MENU *m; 
int *rp, *cp; 

int set_menu_jnark(m, n) 
MENU ♦m; 
char ♦n; 

char *menu_jnark(m) 
MENU *m; 

int scale— menu(m, rp, cp) 
MENU *m; 
int *rp, *cp; 

int set— menu— win(m, w) 
MENU ♦m; 
WINDOW *w; 

WINDOW *menu-win(m) 
MENU *m; 

int set-menu— sub(m, w) 
MENU *m; 
WINDOW *w; 

WINDOW *menu-8ub(m) 
MENU ♦m; 

int set— menu— fore(m, c) 
MENU *m; 
int c; 

int menu— fore(m) 
MENU *m; 
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int set_menu-.back(in, c) 
MENU *in; 
int c; 

int menu— back(m) 
MENU *m; 

int set_Jtnenu_grey(m, c) 
MENU ♦m; 
int c; 

int menii_grey(m) 
MENU *m; 

int set_menu— pad(m, c) 
MENU *m; 
int c; 

int menu-.pad(m) 
MENU ♦m; 

int post_menu(m) 
MENU *m; 

int unposL-menu(m) 
MENU *m; 

int menu-driver(m, c) 
MENU *m; 
int c; 

int set-item— init(m, f) 
MENU *m; 
ITEM ♦ item; 
PTF-void f; 

PTF_void item_init(m) 
MENU *m; 

set_item_term(m, £) 
MENU *m; 
PTF_void f; 

PTE— void item_term(m) 
MENU *m; 

int 8et_menu_Jnit(m, f) 
MENU *m; 
PTF_void f; 

PTF_void menu— init(m) 
MENU *m; 

int set— menu— term(m, f) 
MENU *m; 
PTF-Void f; 

PTE- void menu— term(m) 
MENU *m; 
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int set_current_itein(m, i) 
MENU *m; 
ITEM * item; 

ITEM * current_jtem(m) 
MENU *m; 

int item^ndex(i) 
ITEM * i; 

int set_top_row(m, c) 
MENU ♦m; 
int *c; 

int top_row(m) 
MENU *m; 

int pos_menii_cursor(m) 
MENU *m; 

int set__menii_pattern(m, n) 
MENU *m; 
char *n; 

char 'I'menuL-.patternlm) 
MENU ♦m; 

int set-_menii_userptr(m, n) 
MENU ♦m; 
chr *n; 

char *menu-_userptr(m) 
MENU *m; 

int seL_menu— opts(m, o) 
MENU ♦m; 
OPTIONS o; 

OPTIONS meniL_opts(m) 
MENU *m; 

int menii_opts-_on (m, o) 
MENU *m; 
OPTIONS o; 

int menu_opts-_off (m, o) 
MENU *m; 
OPTIONS o; 



DESCRIPTION 

These routines allow you to create, display, and access menus. Menus can 
be displayed on any display device supported by the low-level Extended 
Terminal Interface (ETI) library curses{3X). Once you compile your program 
includeing the MENU header file menu.h, you should link it with the 
MENU and curses library routines. 
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FUNCTIONS 

The following is a list of MENU routines. For a complete description of 
each, see the UNIX System V ETI Programmer's Guide. 

new_menu(ip) creates a new menu connected to the given item pointer 
array and returns a pointer to the new menu. 

free-jnenudn) disconnects the menu from its associated item pointer array 
and free the storage allocated for the menu. 

set-jnenu-items (m, i) changes the item pointer array connected to the 
given menu to item pointer array i. 

menu—itemsdn) returns a pointer to the item pointer array connected to 
menu m. 

seL_menu_-format(m, c, r) sets the maximum number of rows and columns 
of items that may be displayed at one time on a menu. 

menu— format (m, rp, cp) returns the maximum number of rows and 
columns that may be displayed at one time on a menu, rp and cp are 
pointers to the values used to return these numbers. 

The mark string distinguishes selected items in a multi-valued menu and the 
current item in a single-valued menu. set_meniL_mark(m, n) sets the 
menu's mark string to n. 

menuL-mark(m) returns a pointer to the menu's mark string. 

scale— menu(m, rp, cp) returns the minimum window size necessary for the 
given menu, rp and cp are pointers to the locations used to return the 
number of rows and columns for the menu. 

set__menu__win(m, w) sets window w as the window of menu m. 

menu— win(m) returns a pointer to the menu's window. 

set— menu— sub(m, w) sets window w as the subwindow of menu m. 

menu— sub(m) returns a pointer to the menu's subwindow. 

set— menu— fore (m, c) sets the menu's foreground attribute — the display 
attribute for the current item (if selectable) on single-valued menus and for 
selected items on multi-valued menus. This display attribute is a curses 
visual attribute. By default, this attribute is A_STANDOUT. 

menu— fore (m) returns the menu foreground attribute. 

set— menu— back(m, c) sets the menu's background attribute — the display 
attribute for unselected, yet selectable, items. This display attribute is a 
curses visual attribute. By default, this attribute is A_NORMAL. 

menu— back(m) returns the menu background attribute. 

set— menu— grey(m, c) sets the menu's grey attribute — the display attribute 
for nonselectable items in multi-valued menus. This display attribute is a 
curses visual attribute. By default, this attribute is A—UNDERLINE. 

menu— grey(m) returns the menu's grey attribute. 
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The pad character is the character that fills the space between a menu item's 
name and description, if any. set_jnenu_pad(m, c) sets the pad character 
for menu m to c. 

menu_pad(m) returns the menu's pad character. 

post— menu(m) writes the menu in the menu's subwindow. 

unposL-menu(m) erases the menu from its associated subwindow. 

The workhorse of the menu subsystem, menii_driver(m, c) checks if the 
character c is a menu request or data. If it is a request, the menu driver exe- 
cutes the request and reports the result. If it is data (a printable ASCII char- 
acter), it enters the data into the current position in the current field. If the 
character is not recognized, the menu driver assumes it is an application- 
defined command and returns E_UNKNOWN_COMMAND. 

The following set— functions enable you to establish application routines to 
be executed automatically at initialization and termination points in your 
form application. You need not specify any application-defined initializa- 
tion or termination routines at all, but they may be helpful for displaying 
messages or page numbers and other chores. 

set_itein_init(m, f) sets the application-defined function f to be called 
when the menu is posted and just after the current item changes. 

item_init(m) returns a pointer to the item initialization routine, if any, 
called when the menu is posted and just after the current item changes. 

setJtein_term(m, £) sets function f to be called when the menu is 
unposted and just before the current item changes. 

itein_term(m) returns a pointer to the termination function, if any, called 
when the menu is unposted and just before the current item changes. 

seL-menu_init(in, f) sets the application-defined function f to be called 
when the menu is posted and just after the top row changes on a posted 
menu. 

menu_init(m) returns a pointer to the menu's initialization routine, if any, 
called when the menu is posted and just after the top row changes on a 
posted menu. 

set_menu_term(m, f) sets the application-defined function f to be called 
when the menu is unposted and just before the top row changes on a 
posted menu. 

menu_term(m) returns a pointer to the menu's termination routine, if any, 
called when the menu is unposted and just before the top row changes on a 
posted menu. 

The current item is the item where the cursor is currently positioned. 
set_current-Jtem(m, i) sets the current menu item to the given item. 

current_item(m) returns a pointer to the current item. 

item_Jndex(i) returns the index to the given item in the item pointer array. 

set_top_row(m, c) sets the top of the menu to the named row. The left- 
most item on the new top row becomes the current item. 
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top_j:ow(m) returns the number of the menu row currently displayed at the 
top of the given menu. 

pos_mentL_cursor(in) moves the menu window's cursor to the correct posi- 
tion to resume menu processing. 

Every menu has a pattern buffer to match entered data with menu items. 
set-jnenu_pattern(m, p) sets the pattern buffer to the given pattern and 
tries to find the first item that matches the pattern. If it does, the matching 
item becomes the current item. If not, the current item does not change. 

menu— pattern(m) returns the string in the pattern buffer of the given 
menu. 

Every menu has an associated user pointer that you can use to store per- 
tinent information. 

set— inenu_userptr(m, n) sets the menu's user pointer, 
menu— userptr(m) returns the menu's user pointer. 

set— menu— opts(m, o) turns on the named options for the menu and turns 
off all its remaiiung options. Options are boolean values. Menu options are 
0_ONEVALUE, 0_SHOWDESC, 0_ROWMAJOR, O-IGNORECASE, and 
0_SHOWMATCH. 

menu— opts(m) returns the menu's option setting, 
menu— opts— on (m, opts) turns on the named options for the menu, 
menu— opts— off (m^ opts) turns off the named options for the menu. 
SEE ALSO 

curses(3X), field(3X), fieldtype{3X), form(3X), item(3X), panel(3X), tam(3X). 
The UNIX System V ETI Programmer's Guide. 
DIAGNOSTICS 

The following values are returned by one or more routines that return an 
integer. For specific information on which routine returns which value, see 
the ETI Programmer's Guide. 

E— OK routine returned normally 

E-SYSTEM-ERROR system error 

E— BAD— ARGUMENT an incorrect argument was passed to the rou- 

tine 

E— POSTED menu is already posted 

E— CONNECTED one or more items are connected to another 

menu 

E— BAD— STATE routirie called from an inappropriate routine 

E— NO— ROOM menu does not fit within its subwindow 

E-NOT-POSTED menu has not yet been posted 

E-UNKNOWN-COMMAND 

unrecognizable request was given to the 
driver 
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E_NO_MATCH 
E-NOT__SELECTABLE 
E_NOT_CONNECTED 
E-REQUEST_DENIED 



no match occurred 

item cannot be selected 

no items are associated with the menu 

menu driver could not process the request 
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NAME 

mktemp - make a unique file name 

SYNOPSIS 

char "Cinkteinp (template) 
char "cteinplate; 

DESCRIPTION 

The mktemp function replaces the contents of the string pointed to by tem- 
plate by a unique file name, and returns the address of template. The string 
in template should look like a file name with six trailing Xs; mktemp will 
replace the Xs with a letter and the current process ID. The letter will be 
chosen so that the resulting name does not duplicate an existing file. 

SEE ALSO 

getpid(2), tmpfile(3S), tmpnam(3S). 

DIAGNOSTIC 

The mktemp function will assign to template the NULL string if it cannot 
create a unique name. 

CAVEAT 

If called more than 17,576 times in a single process, this function will start 
recycling previously used names. 
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NAME 

monitor - prepare execution profile 

SYNOPSIS 

#include <mon.h> 

void monitor (lowpc, highpc, buffer, bufsize, nfunc) 
int (*lowpc)( ), (*highpc)( ); 
WORD *buffer; 
int bufsize, nfunc; 

DESCRIPTION 

An executable program created by cc -p automatically includes calls for 
monitor with default parameters; monitor need not be called explicitly except 
to gain fine control over profiling. 

The monitor function is an interface to profil(2). Lowpc and highpc are the 
addresses of tv^o functions; buffer is the address of a user-supplied array of 
bufsize WORDS (defined in the <mon.h> header file), monitor arranges to 
record a histogram of periodically sampled values of the program counter, 
and of counts of calls of certain functions, in the buffer. The lowest address 
sampled is that of lowpc and the highest is just below highpc. Lowpc may 
not equal for this use of monitor. At most nfunc, call counts can be kept; 
only calls of functions compiled with the profiling option -p of cc(l) are 
recorded. 

For the results to be significant, especially where there are small, heavily 
used routines, it is suggested that the buffer be no more than a few times 
smaller than the range of locations sampled. 

To profile the entire program, it is sufficient to use 

extern etext; 

monitor ((int (*)())2, &etext, buf, bufsize, nfunc); 
Etext lies just above all the program text; see end(3C). 
To stop execution monitoring and write the results, use 

monitor ((int (*)())0, 0, 0, 0, 0); 

The prof(l) command can then be used to examine the results. 

The name of the file written by monitor is controlled by the environment 
variable PROFDIR. If PROFDIR does not exist, "mon.out" is created in the 
current directory. If PROFDIR exists but has no value, monitor does not do 
any profiling and creates no output file. Otherwise, the value of PROFDIR is 
used as the name of the directory in which to create the output file. If 
PROFDIR is dimame, then the file written is dirname /pid. mon.oui" where 
pid is the program's process ID. (When monitor is called automatically by 
compiling via cc -p, the file created is ''dimame /pid.progname" where prog- 
name is the name of the program.) 

HLES 

mon.out 
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SEE ALSO 

cc(l), prof(l), profil(2), end(3C). 

BUGS 

The ''dirname/pid.mon.out'' form does not work; the 
''dimame/pid.progname" form (automatically called via cc -p) does work. 
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NAME 

nlist - get entries from name list 

SYNOPSIS 

#include <iilist.h> 

int nlist (filename, nl) 
char "cfilename; 
struct nlist *nl; 

DESCRIPTION 

The nlist function examines the name list in the executable file whose name 
is pointed to by filename, and selectively extracts a list of values and puts 
them in the array of nlist structures pointed to by nl. The name list nl con- 
sists of an array of structures containing names of variables, types, and 
values. The list is terminated with a null name; that is, a null string is in 
the name position of the structure. Each variable name is looked up in the 
name list of the file. If the name is found, the type and value of the name 
are inserted in the next two fields. The type field will be set to unless the 
file was compiled with the -g option. If the name is not found, both entries 
are set to 0. See a.out{4t) for a discussion of the symbol table structure. 
This^ function is useful for examining the system name list kept in the file 
/unix. In this way programs can obtain system addresses that are up to 
date. 

SEE ALSO 

a.out(4). 

DIAGNOSTICS 

All value entries are set to if the file cannot be read or if it does not con- 
tain a valid name list. 

The nlist function returns -1 upon error; otherwise it returns 0. 

NOTES 

The <nlist.h> header file is automatically included by <a.out.h> for compa- 
tibility. However, if the only information needed from <a.out.h> is for use 
of nlist, then including <a,out.h> is discouraged. If <a,out.h> is included, 
the line "#undef n__name" may need to follow it. 
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NAME 

nlsgetcall - get client's data passed via the listener. 

SYNOPSIS 

#include <sys/tiuser.h> 

struct t_call *nlsgetcall(fd); 
int fd; 

DESCRIPTION 

nlsgetcall allows server processes started by the listener process to access the 
client's t—call structure, that is, the sndcall argument of t—Connect(3N), 

The t-^call structure returned by nlsgetcall can be released using t-.free(3N). 

nlsgetcall returns the address of an allocated t—call structure or NULL if a 
t^call structure cannot be allocated. If the t— alloc succeeds, undefined 
environment variables are indicated by a negative len field in the appropri- 
ate netbuf structure. A len field of zero in the netbuf structure is valid and 
means that the original buffer in the listener's t^call structure v^as NULL. 

FILES 

/usr /lib /libnsL-S.a 
/usr/lib /libslan.a 
/usr/lib/libnls.a 

SEE ALSO 

nlsadmin(l), getenv(3), t_connect(3N), t_alloc(3N), t_free(3N), t_error(3N). 
DIAGNOSTICS 

A NULL pointer is returned if a t—call structure cannot be allocated by 
t^lloc. t—.errno can be inspected for further error information. Undefined 
environment variables are indicated by a negative length field (len) in the 
appropriate netbuf structure. 

NOTES 

Server processes must call t^ync(3N) before calling this routine. 
WARNING 

The len field in the netbuf structure is defined as being unsigned. In order 
to check for error returns, it should first be cast to an int. 

CAVEATS 

The listener process limits the amount of user data {udata) and options data 
(opt) to 128 bytes each. Address data addr is limited to 64 bytes. If the ori- 
ginal data was longer, no indication of overflow is given. 
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NAME 

nlsprovider - get name of transport provider. 

SYNOPSIS 

char ^nlsproviderO; 
DESCRIPTION 

nlsprovider returns a pointer to a null terminated character string which con- 
tains the name of the transport provider as placed in the environment by 
the listener process. If the variable is not defined in the environment, a 
NULL pointer is returned. 

The environment variable is only available to server processes started by the 
listener process. 

FILES 

/usr/lib/libslan.a (7300) 
/usr/lib/libnls.a (3B2 Computer) 
/usr /lib /libnsl—s.a 

SEE ALSO 

nlsadmin(lM). 

DIAGNOSTICS 

If the variable is not defined in the environment, a NULL pointer is 
returned. 
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NAME 

nlsrequest - format and send listener service request message 

SYNOPSIS 

#include <listen.h> 

int nlsrequest(fd, service— code); 
int fd; 

char *service_code; 

extern int _nlslog^ t^errno; 

extern char '*'_nlsrmsg; 

DESCRIPTION 

Given a virtual circuit to a listener process (fd) and a service code of a server 
process, nlsrequest formats and sends a service request message to the remote 
listener process requesting that it start the given service, nlsrequest waits for 
the remote listener process to return a service request response message, 
which is made available to the caller in the static, null terminated data 
buffer pointed to by ^nlsrmsg. The service request response message includes 
a success or failure code and a text message. The entire message is print- 
able. 

FILES 

/usr/lib/libnls.a 
/usr /lib /libslan.a 
/usr/lib /libnsLs.a 

SEE ALSO 

nlsadmin(l), L_error(3). 

DIAGNOSTICS 

The success or failure code is the integer return code from nlsrequest. Zero 
indicates success, other negative values indicate nlsrequest failures as fol- 
lows: 

-1: Error encountered by nlsrequest, see t_ermo. 

Positive values are error return codes from the listener process. Mnemonics 
for these codes are defined in listen.h. 

2: Request message not interpretable. 

3: Request service code unknown. 

4: Service code known, but currently disabled. 

If non-null, —nlsrmsg contains a pointer to a static, null terminated character 
buffer containing the service request response message. Note that both 
—nlsrmsg and the data buffer are overwritten by each call to nlsrequest. 

If —nlslog is non-zero, nlsrequest prints error messages on stderr. Initially, 
—nlslog is zero. 

WARNING 

nlsrequest cannot always be certain that the remote server process has been 
successfully started. In this case, nlsrequest returns with no indication of an 
error and the caller will receive notification of a disconnect event via a 
T_LOOK error before or during the first t^nd or t^rcv call. 
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NAME 

panel - PANEL library routines 

SYNOPSIS 

#include <panel.h> 

cc [ flags ] files -Ipanel -Icurses [ libraries ] 
PANEL *new— panel(win) 
WINDOW *win; 

WINDOW *paneL-window(panel) 
PANEL *panel; 

int replace_panel(panel, window) 
PANEL ♦panel; 
WINDOW *window; 

int move_panel(panel, starty, startx) 
PANEL *panel; 
int starty, startx; 

int bottom—paneKpanel) 
PANEL *panel; 

int top_panel(panel) 
PANEL ♦panel- 
void updatcpanelsO 

int hide_panel(panel) 
PANEL *panel; 

int panel— hidden(panel) 
PANEL ♦panel; 

int show— paneKpanel) 
PANEL ♦panel; 

PANEL ♦panel_above(panel) 
PANEL ♦panel; 

PANEL ♦panel— below(panel) 
PANEL ♦panel; 

int ♦set— panel— userptr(panel,ptr) 
PANEL ♦panel- 
char ♦ptr; 

char ♦panel— userptr(panel) 
PANEL ♦panel; 

int del— paneKpanel) 
PANEL ♦panel; 

DESCRIPTION 

Panels are rectangles of text with depth. They enable your windows to 
overlap without having hidden portions of underlying windows be mistak- 
enly visible, stdscr lies beneath all panels. The set of currently visible 
panels is the deck of panels. 
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A window is associated with every panel. The panel routines enable you to 
create panels, fetch their associated windows, shuffle panels in the deck, 
and manipulate panels in other ways. 

PANEL routines run on the AT&T processor line using any terminal sup- 
ported by curses(3X), the low-level Extended Terminal Interface (ETI) 
library. Once you compile your ETI program #includeing the PANEL 
header file paneLh, you should link it with the panel and curses library 
routines. 

FUNCTIONS 

For a complete description of each panel routine, see the UNIX System V ETI 
Programmer's Guide. 

new_panel(win) returns a pointer to a new panel associated with win. 
The new panel is placed on top of the panel deck. 

paneL_window(panel) returns a pointer to the window of panel. 

replace_panel(panel, window) replaces the current window of panel with 
window. 

move— paneKpanel, starty, startx) moves the given panel window so that 
its upper-left comer is at starty, startx. Be sure to use this function, not 
mvwinO, to move a panel window. 

bottom_panel(panel) puts panel at the bottom of all panels. It leaves the 
size and contents of its associated window, and its relations to other panels, 
wholly intact. 

top_panel(panel) puts the given visible panel on top of all panels in the 
deck. 

void update_panels() refreshes the virtual screen to reflect the relations 
between the panels in the deck, but does not call doupdateO to refresh the 
physical screen. 

hide— paneKpanel) removes the panel from the panel deck and thus hides it 
from view. The panel's internal data structure, however, is retained. 

panel— hidden(panel) returns a boolean value indicating whether or not the 
given panel has been removed from the panel deck. 

show— paneKpanel) makes a hidden panel visible by placing it on top of 
the panels in the panel deck. 

panel— above(panel) returns a pointer to the panel just above panel. If the 
panel argument is NULL, i.e., (panel *) 0, it returns a pointer to the bottom 
panel in the deck. 

panel— below(panel) returns a pointer to the panel just below panel. If the 
panel argument is NULL, it returns a pointer to the top panel in the deck. 

set— panel— userptr(panel,ptr) sets the panel's user pointer. 

panel— userptr(panel) returns the user pointer for a given panel. 

del— paneKpanel) deletes the panel, but not its associated window. 
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SEE ALSO 

curses(3X), field(3X), fieldtype(3X), form(3X), item(3X), menu(3X), tam(3X). 
The UNIX System V ETI Programmer's Guide, 
DIAGNOSTICS 

Each panel routine that returns a pointer to an object returns NULL if an 
error occurs. Each panel routine that returns an int value returns OK if it 
executes successfully and ERR if not. 
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NAME 

perror, ermo, sys_errlist, sys__nerr - system error messages 

SYNOPSIS 

void perror (s) 
char *s; 

extern int errno; 
extern char *sys_errlist[ ]; 
extern int sys—nerr; 
DESCRIPTION 

The perror function produces a message on the standard error output, 
describing the last error encountered during a call to a system or library 
function. The argument string s is printed first, then a colon and a blank, 
then the message and a new-line. (However, if s="", the colon is not 
printed.) To be of most use, the argument string should include the name 
of the program that incurred the error. The error number is taken from the 
external variable ermo, which is set when errors occur but not cleared when 
non-erroneous calls are made. 

To simplify variant formatting of messages, the array of message strings 
sys^rrlist is provided; ermo can be used as an index into this table to get 
the message string without the new-line. Sys—tierr is the number of mes- 
sages in the table; it should be checked because new error codes may be 
added to the system before they are added to the table. 

SEE ALSO 

intro(2). 



- 1 - 



PLOT(3X) 



(C Software Development Set) 



PLOT(3X) 



NAME 

plot - graphics interface subroutines 

SYNOPSIS 

openpl 

erase () 

label (s) 
char *s; 

line (xl, yl, x2, y2) 
int xl, yl, x2, yl; 

circle (x, y, r) 
int X, y, r; 

arc (X, y, xO, yO, xl, yl) 
int X, y, xO, yO, xl, yl; 

move (x, y) 
int X, y; 

cont (x, y) 
int X, y; 

point (x, y) 
int X, y; 

linemod (s) 
char *s; 

space (xO, yO, xl, yl) 
int xO, yO, xl, yl; 

closepl 

DESCRIPTION 

These subroutines generate graphic output in a relatively device- 
independent manner. Space must be used before any of these functions to 
declare the amount of space necessary [see plot{4)]. Openpl must be used 
before any of the others to open the device for v^riting. Closepl flushes the 
output. 

Circle draws a circle of radius r with center at the point (x, y). 

Arc draws an arc of a circle with center at the point (x, y) between the points 
(xO, yO) and (xl, yl). 

String arguments to label and linemod are terminated by nulls and do not 
contain new-lines. 

See plot{4:) for a description of the effect of the remaining functions. 
The library files listed below provide several flavors of these routines. 

FILES 

LIBDIR/libplot.a produces output for tplot{lG) filters 

LIBDIR/lib300.pa for DASI 300 
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LIBDIR/lib300.a 
LIBDIR/lib450.a 
LIBDIR/lib4014.a 



for DASI 300s 



for DASI 450 



for TEKTRONIX 4014 



LIBDIRusually /usr/lib 

SEE ALSO 

pIot(4). 

graph(lG), stat(lG), tpIot(lG) in the Usefs/System Administrator's Reference 
Manual. 

WARNINGS 

In order to compile a program containing these functions in file.c, it is 
necessary to use "cc file.c -Iplot". 

In order to execute it, it is necessary to use "a.out I tplot". 

The above routines use <stdio.h>, which causes them to increase the size 
of programs, not otherwise using standard I/O more than might be 



expected. 
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NAME 

popen, pclose - initiate pipe to/from a process 

SYNOPSIS 

#mclude <stdio.h> 

FILE ♦popen (command, type) 
char ^command, '''type; 

int pclose (stream) 
FILE ^stream; 

DESCRIPTION 

The popen function creates a pipe between the calling program and the 
command to be executed. The arguments to popen are pointers to null- 
terminated strings. Command consists of a shell command line. Type is an 
I/O mode, either r for reading or w for writing. The value returned is a 
stream pointer such that one can write to the standard input of the com- 
mand, if the I/O mode is w, by writing to the file stream; and one can read 
from the standard output of the command, if the I/O mode is r, by reading 
from the file stream . 

A stream opened by popen should be closed by pclose, which waits for the 
associated process to terminate and returns the exit status of the command. 

Because open files are shared, a type r command may be used as an input 
filter and a type w as an output filter. 

EXAMPLE 

A typical call may be: 

char *cmd = "Is *.c"; 
FILE *ptr; 

if ((ptr = popen(cmd, "r")) != NULL) 
while (fgets(buf, n, ptr) != NULL) 
(void) printf("%s ",buf); 

This will print in stdout [see stdio (3S)] all the file names in the current 
directory that have a ".c" suffix. 

SEE ALSO 

pipe(2), wait(2), fclose(3S), fopen(3S), stdio(3S), system(3S). 
DL\GNOSTICS 

The popen function returns a NULL pointer if files or processes cannot be 
created. 

The pclose function returns -1 if stream is not associated with a "popen ed" 
command. 

WARNING 

If the original and popen ed." processes concurrently read or write a com- 
mon file, neither should use buffered I/O. Problems with an output filter 
may be forestalled by careful buffer flushing, e.g., v^dth fflush [see fclose{3S)]. 
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NAME 

printf, fprintf, sprintf - print formatted output 

SYNOPSIS 

#include <stdio.h> 

int printf (format , arg ... ) 
char ^format; 

int fprintf (stream, format , arg ... ) 
FILE ^stream; 
char ^format; 

int sprintf (s, format [ , arg ] . . . ) 
char *s, *format; 

DESCRIPTION 

The printf function places output on the standard output stream stdout. 
Fprintf places output on the named output stream. Sprintf places "output," 
followed by the null character (\0), in consecutive bytes starting at *s; it is 
the user's responsibility to ensure that enough storage is available. Each 
function returns the number of characters transmitted (not including the \0 
in the case of sprintf), or a negative value if an output error was encoun- 
tered. 

Each of these functions converts, formats, and prints its args under control 
of the format. The format is a character string that contains three t5rpes of 
objects: plain characters, which are simply copied to the output stream; 
escape sequences that represent non-graphic characters; and conversion 
specifications, each of which results in fetching of zero or more args. The 
results are undefined if there are insufficient args for the format. If the for- 
mat is exhausted while args remain, the excess args are simply ignored. 

Each conversion specification is introduced by the character %. After the %, 
the following appear in sequence: 

Zero or more flags, which modify the meaning of the conversion 
specification. 

An optional, decimal digit string specifying a minimum field width . 
If the converted value has fewer characters than the field width, it 
vdll be padded on the left (or right, if the left-adjustment flag 
described below, has been given) to the field width. The padding is 
vdth blanks unless the field width digit string starts with a zero, in 
which case the padding is with zeros. 

A precision that gives the minimum number of digits to appear for 
the d, i, o, u, x, or X conversions, the number of digits to appear 
after the decimal point for the e, E, and f conversions, the maximum 
number of significant digits for the g and G conversion, or the max- 
imum number of characters to be printed from a string in s conver- 
sion. The precision takes the form of a period (.) followed by a 
decimal digit string; a null digit string is treated as zero. Padding 
specified by the precision overrides the padding specified by the 
field v^dth. 
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An optional 1 (ell) specifying that a following d, i, o, u, x, or X 
conversion character applies to a long integer arg. An 1 before any 
other conversion character is ignored. 

A character that indicates the type of conversion to be applied. 

A field w^idth or precision or both may be indicated by an asterisk (*) 
instead of a digit string. In this case, an integer arg supplies the field width 
or precision. The arg that is actually converted is not fetched until the 
conversion letter is seen, so the args specifying field width or precision must 
appear before the arg (if any) to be converted. A negative field width argu- 
ment is taken as a flag followed by a positive field width. If the precision 
argument is negative, it will be changed to zero. 

The flag characters and their meanings are: 

The result of the conversion will be left-justified within the field. 
+ The result of a signed conversion will always begin with a sign 

(+ or -). 

blank If the first character of a signed conversion is not a sign, a blank 
will be prefbced to the result. This implies that if the blank and 
+ flags both appear, the blank flag will be ignored. 

# This flag specifies that the value is to be converted to an "alter- 

nate form." For c, d, i, s, and u conversions, the flag has no 
effect. For o conversion, it increases the precision to force the 
first digit of the result to be a zero. For x or X conversion, a 
non-zero result will have Ox or OX prefixed to it. For e, E, f, g, 
and G conversions, the result will always contain a decimal 
point, even if no digits follow the point (normally, a decimal 
point appears in the result of these conversions only if a digit 
follows it). For g and G conversions, trailing zeroes will not be 
removed from the result (which they normally are). 

The conversion characters and their meanings are: 

d, i,o,u,x,X The integer arg is converted to signed decimal (d or i), unsigned 

octal, (o), decimal (u), or hexadecimal notation (x or X), respec- 
tively; the letters abcdef are used for x conversion and the letters 
ABCDEF for X conversion. The precision specifies the minimum 
number of digits to appear; if the value being converted can be 
represented in fewer digits, it will be expanded with leading 
zeroes. The default precision is 1. The result of converting a 
zero value with a precision of zero is a null string. 

f The float or double arg is converted to decimal notation in the 

style "[-]ddd.ddd," where the number of digits after the decimal 
point is equal to the precision specification. If the precision is 
missing, six digits are output; if the precision is explicitiy 0, no 
decimal point appears. 

e, E The float or double arg is converted in the style "[-]d.ddde±dd," 

where there is one digit before the decimal point and the number 
of digits after it is equal to the precision; when the precision is 
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missing, six digits are produced; if the precision is zero, no 
decimal point appears. The E format code will produce a 
number with E instead of e introducing the exponent. The 
exponent always contains at least two digits. 

g,G The float or double arg is printed in style f or e (or in style E in 

the case of a G format code), with the precision specifying the 
number of significant digits. The style used depends on the 
value converted: style e vsdll be used only if the exponent result- 
ing from the conversion is less than -4 or greater than the preci- 
sion. Trailing zeroes are removed from the result; a decimal 
point appears only if it is followed by a digit. 

c The character arg is printed. 

s The arg is taken to be a string (character pointer) and characters 

from the string are printed until a null character (\0) is encoun- 
tered or the number of characters indicated by the precision 
specification is reached. If the precision is missing, it is taken to 
be infinite, so all characters up to the first null character are 
printed. A NULL value for arg will yield undefined results. 

% Print a %; no argument is converted. 

In printing floating point types (float and double), if the exponent is 0x7FF 
and the mantissa is not equal to zero, then the output is 

[-]NaNOxdddddddd 
where Oxdddddddd is the hexadecimal representation of the leftmost 32 bits 
of the mantissa. If the mantissa is zero, the output is 

[±]inf. 

In no case does a nonexistent or small field width cause truncation of a 
field; if the result of a conversion is wider than the field width, the field is 
simply expanded to contain the conversion result. Characters generated by 
printf and fprintf are printed as if ;7«^c(3S) had been called. 

EXAMPLES 

To print a date and time in the form "Sunday, July 3, 10:02," where week- 
day and month are pointers to null-terminated strings: 

printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min); 

To print tt to 5 decimal places: 

printf("pi = %.5f", 4 * atan(l.O)); 

SEE ALSO 

ecvt(3C), putc(3S), scanf(3S), stdio(3S). 



- 3 - 



PUTC(3S) 



(C Software Development Set) 



PUTC(3S) 



NAME 

putc, putchar, fputc, putw - put character or word on a stream 

SYNOPSIS 

#include <stdio.h> 

int putc (c, stream) 
int c; 

FILE «stream; 

int putchar (c) 
int c; 

int fputc (c, stream) 
int c; 

FILE ^stream; 

int putw (w, stream) 
int w; 

FILE ♦stream; 
DESCRIPTION 

The putc function writes the character c onto the output stream (at the posi- 
tion where the file pointer, if defined, is pointing). putchar{c) is defined as 
putc(c, stdout). putc and putchar are macros. 

Fputc behaves like putc, but is a function rather than a macro. Fputc runs 
more slowly than putc, but it takes less space per invocation and its name 
can be passed as an argument to a function. 

Putw writes the word (i.e., integer) w to the output stream (at the position 
at which the file pointer, if defined, is pointing). The size of a word is the 
size of an integer and varies from machine to machine. Putw neither 
assumes nor causes special alignment in the file. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), printf(3S), puts(3S), setbuf(3S), 
stdio(3S). 

DIAGNOSTICS 

On success, these functions (with the exception of putw) each return the 
value they have written. [Putw returns ferror (stream).] On failure, they 
return the constant EOF. This will occur if the file stream is not open for 
vmting or if the output file cannot grow. Because EOF is a valid integer, 
ferror{3S) should be used to detect putw errors. 

CAVEATS 

Because it is implemented as a macro, putc evaluates a stream argument 
more than once. In particular, putc(c, *f-f +) doesn't work sensibly. Fputc 
should be used instead. 

Because of possible differences in word length and byte ordering, files writ- 
ten using putw are machine-dependent, and may not be read using getw on 
a different processor. 
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NAME 

putenv - change or add value to environment 

SYNOPSIS 

int putenv (string) 
char ^string; 

DESCRIPTION 

String points to a string of the form "name=value/' The putenv function 
makes the value of the environment variable name equal to value by alter- 
ing an existing variable or creating a new one. In either case, the string 
pointed to by string becomes part of the environment, so altering the string 
will change the environment. The space used by string is no longer used 
once a new string defining name is passed to putenv, 

SEE ALSO 

exec(2), getenv(3C), malloc{3C), environ(5). 

DIAGNOSTICS ^ . , 

The putenv function returns non-zero if it was unable to obtam enough 
space via malloc for an expanded environment, otherwise zero. 

WARNINGS 

The putenv function manipulates the environment pomted to by environ, 
and can be used in conjunction with getenv. However, envp (the third argu- 
ment to main) is not changed. 

This routine uses malloc(^C) to enlarge the environment. 
After putenv is called, environmental variables are not in alphabetical order. 
A potential error is to call putenv with an automatic variable as the argu- 
ment, then exit the calling function while string is still part of the environ- 
ment. 
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NAME 

putpwent - write password file entry 

SYNOPSIS 

#include <pwd.ii> 

int putpwent (p, f) 
struct passwd *p; 
FILE *f; 

DESCRIPTION 

The putpwent function is the inverse of getpwent {3C). Given a pointer to a 
passwd structure created by getpwent (or getpwuid or getpwnam), putpwent 
vmtes a line on the stream /, which matches the format of /etc/passwd. 
SEE ALSO 

getpwent(3C). 

DIAGNOSTICS 

The putpwent function returns non-zero if an error was detected during its 
operation, otherwise zero. 

WARNING 

The above routine uses <stdio.h>, which causes it to increase the size of 
programs, not otherwise using standard I/O, more than might be expected. 



- 1 - 



PUTS(3S) 



(C Software Development Set) 



PUTS(3S) 



NAME 

puts, fputs - put a string on a stream 

SYNOPSIS 

#include <stdio.h> 

int puts (s) 
char *s; 

int fputs (s, stream) 
char *s; 
FILE *stream; 

DESCRIPTION 

The puts function writes the null-terminated string pointed to by s, followed 
by a new-line character, to the standard output stream stdout 

Fputs writes the null-terminated string pointed to by s to the named output 
stream. 

Neither function writes the terminating null character. 
SEE ALSO 

ferror(3S), fopen(3S), fread(3S), printf(3S), putc(3S), stdio(3S). 
DIAGNOSTICS 

Both routines return EOF on error. This will happen if the routines try to 
write on a file that has not been opened for writing. 

NOTES 

The puts function appends a new-line character while fputs does not. 
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NAME 

qsort - quicker sort 
SYNOPSIS 

void qsort ((char *) base, nel, sizeof (♦base), compar) 
unsigned nel; 
int (*compar)( ); 

DESCRIPTION 

The qsort function is an implementation of the quicker-sort algorithm. It 
sorts a table of data in place. 

Base points to the element at the base of the table. Nel is the number of 
elements in the table. Compar is the name of the comparison function, 
which is called with two arguments that point to the elements being com- 
pared. The comparison function must return an integer less than, equal to, 
or greater than zero, according to whether the first argument is to be con- 
sidered as less than, equal to, or greater than the second argument. 
SEE ALSO 

bsearch(3C), lsearch(3C), string(3C). 

sort(l) in the User's /System Administrator's Reference Manual. 

NOTES 

The pointer to the base of the table should be of type pointer-to-element, 
and cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data 
may be contained in the elements in addition to the values being compared. 
The order in the output of two items which compare as equal is unpredict- 
able. 



- 1 - 



RAND(3C) 



(C Software Development Set) 



RAND(3C) 



NAME 

rand, srand - simple random-number generator 

SYNOPSIS 

int rand ( ) 

void srand (seed) 
unsigned seed; 

DESCRIPTION 

The rand function uses a multiplicative congruential random-number gen- 
erator with period 2^^ that returns successive pseudo-random numbers in 
the range from to 2^^-l. 

The srand function can be called at any time to reset the random-number 
generator to a random starting point. The generator is initially seeded with 
a value of 1. 

SEE ALSO 

drand48(3C). 

NOTES 

The spectral properties of rand are limited. The drand48 {3C) function pro- 
vides a much better, though more elaborate, random-number generator. 

The foUov^ing functions define the semantics of the functions rand and 
srand. 

static unsigned long int next = 1; 

int rand( ) 

{ 

next = next * 1103515245 + 12345; 

return ((unsigned int) (next/65536) % 32768); 

} 

void srand(seed) 
unsigned int seed; 
{ 

next = seed; 

} 

Specifying the semantics makes it possible to reproduce the behavior of pro- 
grams that use pseudo-random sequences. This facilitates the testing of 
portable applications in different implementations. 



- 1 - 



REGCMP(3X) 



(C Software Development Set) 



REGCMP(3X) 



NAME 

regcmp, regex - compile and execute regular expression 
SYNOPSIS 

char *regcmp (stringl [, string2, ...], (char *)0) 
char *stringl, *string2, 

char ♦regex (re, subject[, retO, ...]) 
char *re, ^subject, *retO, 

extern char * loci; 

DESCRIPTION 

The regcmp function compiles a regular expression (consisting of the con- 
catenated arguments) and returns a pointer to the compiled form. The 
malloc(3C) function is used to create space for the compiled form. It is the 
user's responsibility to free unneeded space so allocated. A NULL return 
from regcmp indicates an incorrect argument. regcmp{\) has been written to 
generally preclude the need for this routine at execution time. 

Regex executes a compiled pattern against the subject string. Additional 
arguments are passed to receive values back. Regex returns NULL on failure 
or a pointer to the next unmatched character on success. A global character 

pointer loci points to where the match began, regcmp and regex were 

mostly borrowed from the editor, ed{\); however, the syntax and semantics 
have been changed slightly. The following are the valid symbols and their 
associated meanings. 
These S)niibols retain their meaning in 
ed{\). 

By necessity, all the above defined symbols are special. 

They must, therefore, be escaped with a \ (backslash) to be used as 

themselves. 

EXAMPLES 

Example 1: 

char *cursor, *newcursor, *ptr; 

newcursor = regex((ptr = regcmp("\n", (char *)0)), cursor); 
free(ptr); 

This example will match a leading new-line in the subject string pointed at 
by cursor. 

Example 2: 

char ret0[9]; 

char *newcursor, *name; 

name = regcmp("([A-Za-z][A-za-zO-9]{0,7})0, (char m; 

This example will match through the string "TestingS" and will return the 
address of the character after the last matched character (the "4"). The 
string "TestingS" will be copied to the character array retO. 



- 1 - 



REGCMP(3X) 



(C Software Development Set) 



REGCMP(3X) 



Example 3: 

#include "file.i" 

char *string, *newcursor; 

newcursor = regex(name, string); 

This example applies a precompiled regular expression in file.i [see 
regcmp(l)] against string. 

SEE ALSO 

regcmp(l), regexp(5), malloc(3C). 

ed(l) in the User's /System Administrator's Reference Manual. 

BUGS 

The user program may run out of memory if regcmp is called iteratively 
without freeing the vectors no longer required. 
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NAME 

scanf, fscanf, sscanf - convert formatted input 

SYNOPSIS 

#include <stdio.h> 

int scanf (format [ , pointer ] . . . ) 
char «format; 

int fscanf (stream, format [ , pointer ] . . . ) 
FILE ^stream; 
char ^format; 

int sscanf (s, format [ , pointer ] . . . ) 
char *s, «format; 

DESCRIPTION 

The scanf function reads from the standard input stream stdin, Fscanf reads 
from the named input stream. Sscanf reads from the character string s. 
Each function reads characters, interprets them according to a format, and 
stores the results in its arguments. Each expects, as arguments, a control 
string format described belov^, and a set of pointer arguments indicating 
where the converted input should be stored. The results are undefined in 
that there are insufficient args for the format. If the format is exhausted 
while args remain, the excess args are simply ignored. 

The control string usually contains conversion specifications, which are used 
to direct interpretation of input sequences. The control string may contain: 

1. White-space characters (blanks, tabs, new-lines, or form-feeds) which, 
except in two cases described below, cause input to be read up to the 
next non-white-space character. 

2. An ordinary character (not %), which must match the next character of 
the input stream. 

3. Conversion specifications, consisting of the character %, an optional 
assignment suppressing character *, an optional numerical maximum 
field width, an optional I (ell) or h indicating the size of the receiving 
variable, and a conversion code. 

A conversion specification directs the conversion of the next input field; the 
result is placed in the variable pointed to by the corresponding argument, 
unless assignment suppression was indicated by *. The suppression of 
assignment provides a way of describing an input field which is to be 
skipped. An input field is defined as a string of non-space characters; it 
extends to the next inappropriate character or until the field width, if speci- 
fied, is exhausted. For all descriptors except and "c", white space lead- 
ing an input field is ignored. 

The conversion code indicates the interpretation of the input field; the 
corresponding pointer argument must usually be of a restricted type. For a 
suppressed field, no pointer argument is given. The following conversion 
codes are legal: 

% a single % is expected in the input at this point; no assignment is 
done. 
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a decimal integer is expected; the corresponding argument should be 
an integer pointer. 

an unsigned decimal integer is expected; the corresponding argu- 
ment should be an unsigned integer pointer. 

an octal integer is expected; the corresponding argument should be 
an integer pointer. 

a hexadecimal integer is expected; the corresponding argument 
should be an integer pointer. 

an integer is expected; the corresponding argument should be an 
integer pointer. It will store the value of the next input item inter- 
preted according to C conventions: a leading "0" implies octal; a 
leading "Ox" implies hexadecimal; otherwise, decimal. 

stores in an integer argument the total number of characters (includ- 
ing white space) that have been scanned so far since the function 
call. No input is consumed. 

a floating point number is expected; the next field is converted 
accordingly and stored through the corresponding argument, which 
should be a pointer to a float. The input format for floating point 
numbers is an optionally signed string of digits, possibly containing 
a decimal point, followed by an optional exponent field consisting 
of an E or an e, followed by an optional + or - , followed by an 
integer. 

a character string is expected; the corresponding argument should be 
a character pointer pointing to an array of characters large enough 
to accept the string and a terminating \0, which will be added 
automatically. The input field is terminated by a white-space char- 
acter. 

a character is expected; the corresponding argument should be a 
character pointer. The normal skip over white space is suppressed 
in this case; to read the next non-space character, use %l8. If a field 
width is given, the corresponding argument should refer to a char- 
acter array; the indicated number of characters is read. 

indicates string data and the normal skip over leading white space is 
suppressed. The left bracket is followed by a set of characters, 
which we will call the scanset, and a right bracket; the input field is 
the maximal sequence of input characters^ consisting entirely of char- 
acters in the scanset. The circumflex (^), when it appears as the 
first character in the scanset, serves as a complement operator and 
redefines the scanset as the set of all characters not contained in the 
remainder of the scanset string. There are some conventions used 
in the construction of the scanset. A range of characters may be 
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represented by the construct first-last, thus [0123456789] may be 
expressed [0-9]. Using this convention, first must be lexically less 
than or equal to last, or else the dash will stand for itself. The dash 
will also stand for itself whenever it is the first or the last character 
in the scanset. To include the right square bracket as an element of 
the scanset, it must appear as the first character (possibly preceded 
by a circumflex) of the scanset, and in this case it will not be syntac- 
tically interpreted as the closing bracket. The corresponding argu- 
ment must point to a character array large enough to hold the data 
field and the terminating \0, which will be added automatically. At 
least one character must match for this conversion to be considered 
successful. 

The conversion characters d, u, o, x and i may be preceded by 1 or h to 
indicate that a pointer to long or to short rather than to int is in the argu- 
ment list. Similarly, the conversion characters e, f, and g may be preceded 
by 1 to indicate that a pointer to double rather than to float is in the argu- 
ment list. The 1 or h modifier is ignored for other conversion characters. 

The scanf function conversion terminates at EOF, at the end of the control 
string, or when an input character conflicts with the control string. In the 
latter case, the offending character is left unread in the input stream. 

The scanf function returns the number of successfully matched and assigned 
input items; this number can be zero in the event of an early conflict 
between an input character and the control string. If the input ends before 
the first conflict or conversion, EOF is returned. 

EXAMPLES 

The call: 

int n ; float x; char name[50]; 

n = scanf ("%d%f%s", &i, &x, name); 

vsdth the input line: 

25 54.32E-1 thompson 

will assign to n the value 3, to i the value 25, to x the value 5.432, and 
name will contain thompson\0 . Or: 

int i, j; float x; char name[50]; 

(void) scanf ("%i%2d%f%*d %[0-9] &j, &i, &x, name); 

with input: 

Oil 56789 0123 56a72 

will assign 9 to 56 to z, 789.0 to x, skip 0123, and place the string 56\0 in 
name. The next call to getchar [see getc(3S)] will return a. Or: 

int i, j, s, e; char name[50]; 

(void) scanf ("%i %i %n%s%n", &i, &j, &s, name, &e); 
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with input: 

0x11 Oxy johnson 

will assign 17 to f , to 6 to s, will place the string xy\0 in name, and will 
assign 8 to e. Thus, the length of name is e - s = 2 . The next call to 
getchar [see getc{3S)] will return a blank. 

SEE ALSO 

getc(3S), printf{3S), stdio(3S), strtod(3C), strtol{3C). 
DIAGNOSTICS 

These functions return EOF on end of input and a short count for missing or 
illegal data items. 
CAVEATS 

Trailing white space (including a new-line) is left unread unless matched in 
the control string. 
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NAME 

setbuf, setvbuf - assign buffering to a stream 

SYNOPSIS 

#include <stdio.h> 

void setbuf (stream, buf) 
FILE ♦stream; 
char *buf; 

int setvbuf (stream, buf, type, size) 
FILE ^stream; 
char *buf; 
int type, size; 

DESCRIPTION 

The setbuf function may be used after a stream has been opened but before 
it is read or written. It causes the array pointed to by buf to be used instead 
of an automatically allocated buffer. If buf is the NULL pointer, 
input/output will be completely unbuffered. 

A constant BUFSIZ, defined in the <stdio.h> header file, tells how big an 
array is needed: 

char buf[BUFSIZ]; 

Setvbuf may be used after a stream has been opened but before it is read or 
written. Type determines how stream will be buffered. Legal values for 
type (defined in stdio.h) are: 

-lOFBF causes input/output to be fully buffered. 

_IOLBF causes output to be line buffered; the buffer will be flushed 

when a newline is written, the buffer is full, or input is 
requested. 

-lONBF causes input/output to be completely unbuffered. 

If buf is not the NULL pointer, the array it points to will be used for buffer- 
ing, instead of an automatically allocated buffer. Size specifies the size of 
the buffer to be used. The constant BUFSIZ in <stdio.h> is suggested as a 
good buffer size. If input/output is unbuffered, buf and size are ignored. 

By default, output to a terminal is line-buffered and all other input/output 
is fully buffered. 

SEE ALSO 

fopen(3S), getc(3S), malloc(3C), putc(3S), stdio(3S). 
DIAGNOSTICS 

If an illegal value for type or size is provided, setvbuf returns a non-zero 
value. Otherwise, the value returned will be zero. 

NOTES 

A common source of error is allocating buffer space as an "automatic" vari- 
able in a code block, and then failing to close the stream in the same block. 
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NAME 

setjmp, longjmp - non-local goto 

SYNOPSIS 

#include <setjmp.h> 

int setjmp (env) 
jmp^buf env; 

void longjmp (env, val) 
jmp_buf env; 
int val; 

DESCRIPTION 

These functions are useful for dealing with errors and interrupts encoun- 
tered in a low-level subroutine of a program. 

setjmp saves its stack environment in env (whose type, jmp—buf, is defined 
in the <setjinp.h> header file) for later use by longjmp. It returns the value 
0. 

longjmp restores the environment saved by the last call of setjmp with the 
corresponding env argument. After longjmp is completed, program execu- 
tion continues as if the corresponding call of setjmp had just returned the 
value val . longjmp cannot cause setjmp to return the value 0. If longjmp is 
invoked with a second argument of 0, setjmp will return 1. At the time of 
the second return from setjmp, all external and static variables have values 
as of the time longjmp is called (see example). The values of register and 
automatic variables are undefined. 

In a future release, C language users will be able to identify syntactically 
those automatic variables on whose values they need to rely after the 
second return from setjmp, 

EXAMPLE 

#include <setjmp.h> 

jmp_buf env; 
int i = 0; 
main ( ) 
{ 

void exit ( ) ; 

if ( set jmp( env) != 0) { 

(void) printf ( "value of i on 2nd return from setjmp: %d\n", i); 
exit ( ) ; 

} 

(void) printf( "value of i on 1st return from setjmp: %d\n" , i); 
i = 1; 

g( ) ; 

/♦NOTREACHED*/ 

} 

g( ) 
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{ 

long jmp ( env , 1 ) ; 
/♦NOTREACHED*/ 

} 

If the a.out resulting from this C language code is run, the output will be: 
value of i on 1st return from setjmp:0 
value of i on 2nd return from setjmp: 1 

SEE ALSO 

signal(2). 

WARNING 

Problems may occur if longjmp is called before env is primed with a call to 
setjmp. 
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NAME 

sinh, cosh, tanh - hyperbolic functions 

SYNOPSIS 

#include <math.h> 

double sinh (x) 
double x; 

double cosh (x) 
double x; 

double tanh (x) 
double x; 

DESCRIPTION 

The sinh, cosh, and tanh functions return, respectively, the hyberbolic sine, 
cosine and tangent of their argument. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

The sinh and cosh functions return HUGE (and sinh may return -HUGE for 
negative x) when the correct value would overflow and set errno to 
ERANGE. 

These error-handling procedures may be changed with the function 
matherr(3M). 
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NAME 

sleep - suspend execution for interval 

SYNOPSIS 

unsigned sleep (seconds) 
unsigned seconds; 

DESCRIPTION 

The current process is suspended from execution for the number of seconds 
specified by the argument. The actual suspension time may be less than 
that requested for two reasons: (1) Because scheduled v^akeups occur at 
fixed 1 -second intervals, (on the second, according to an internal clock) and 
(2) because any caught signal v^U terminate the sleep foUovy^ing execution of 
that signal's catching routine. Also, the suspension time may be longer 
than requested by an arbitrary amount due to the scheduling of other 
activity in the system. The value returned by sleep will be the "unslept" 
amount (the requested time minus the time actually slept) in case the caller 
had an alarm set to go off earlier than the end of the requested sleep time, 
or premature arousal due to another caught signal. 

The routine is implemented by setting an alarm signal and pausing until it 
(or some other signal) occurs. The previous state of the alarm signal is 
saved and restored. The calling program may have set up an alarm signal 
before calling sleep. If the sleep time exceeds the time till such alarm signal, 
the process sleeps only until the alarm signal would have occurred. The 
caller's alarm catch routine is executed just before the sleep routine returns. 
But if the sleep time is less than the time till such alarm, the prior alarm 
time is reset to go off at the same time it would have without the interven- 
ing sleep, 

SEE ALSO 

alarm(2), pause(2), signal(2). 
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NAME 

sputl, sgetl - access long integer data in a machine-independent fashion 

SYNOPSIS 

void sputl (value, buffer) 
long valued- 
char *buffer; 

long sgetl (buffer) 
char *buffer; 

DESCRIPTION 

sputl takes the four bytes of the long integer value and places them in 
memory starting at the address pointed to by buffer. The ordering of the 
bytes is the same across all machines. 

sgetl retrieves the four bytes in memory starting at the address pointed to 
by buffer and returns the long integer value in the byte ordering of the host 
machine. 

The combination of sputl and sgetl provides a machine-independent way of 
storing long numeric data in a file in binary form without conversion to 
characters. 

A program that uses these functions must be loaded with the object- file 
access routine library libld.a. 
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NAME 

ssignal, gsignal - software signals 

SYNOPSIS 

#include <signaLh> 

int ('i'ssignal (sig, action))( ) 
int sig, ('I'actionX ); 

int gsignal (sig) 
int sig; 

DESCRIPTION 

The ssignal and gsignal functions implement a software facility similar to 
signal (2). This facility is used by the Standard C Library to enable users to 
indicate the disposition of error conditions, and is also made available to 
users for their own purposes. 

Software signals made available to users are associated with integers in the 
inclusive range 1 through 16. A call to ssignal associates a procedure, action, 
with the software signal sig; the software signal, sig, is raised by a call to 
gsignal. Raising a software signal causes the action established for that sig- 
nal to be taken . 

The first argument to ssignal is a number identifying the type of signal for 
which an action is to be established. The second argument defines the 
action; it is either the name of a (user-defined) action function or one of the 
manifest constants SIG_DFL (default) or SIG_IGN (ignore). The ssignal func- 
tion returns the action previously established for that signal type; if no 
action has been established or the signal number is illegal, ssignal returns 
SIG_DFL. 

The gsignal function raises the signal identified by its argument, sig: 

If an action function has been established for sig, then that action is 
reset to SIG_DFL and the action function is entered with argument sig, 
Gsignal returns the value returned to it by the action function. 

If the action for sig is SIG_IGN, gsignal returns the value 1 and takes 
no other action. 

If the action for sig is SIG_DFL, gsignal returns the value and takes 
no other action. 

If sig has an illegal value or no action was ever specified for sig, gsig- 
nal returns the value and takes no other action. 

SEE ALSO 

signal(2), sigset(2). 

NOTES 

There are some additional signals with numbers outside the range 1 through 
16 which are used by the Standard C Library to indicate error conditions. 
Thus, some signal numbers outside the range 1 through 16 are legal, 
although their use may interfere with the operation of the Standard C 
Library. 
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NAME 

stdio - standard buffered input/output package 

SYNOPSIS 

#include <stdio.h> 

FILE *stdin, «stdout, *stderr; 

DESCRIPTION 

The functions described in the entries of sub-class 3S of this manual consti- 
tute an efficient, user-level I/O buffering scheme. The in-line macros 
getc (33) and putc (33) handle characters quickly. The macros getchar and 
putchar, and the higher-level routines fgetc, fgets, fprintf, fputc, fputs, fread, 
fscanf, fwrite, gets, getw, printf, puts, putiv, and scanf all use or act as if they 
use getc and putc; they can be freely intermixed. 

A file v^th associated buffering is called a stream and is declared to be a 
pointer to a defined type FILE. The fopen{33) function creates certain 
descriptive data for a stream and returns a pointer to designate the stream in 
all further transactions. Normally, there are three open streams with con- 
stant pointers declared in the <stdio.h> header file and associated v^ith the 
standard open files: 

stdin standard input file 
stdout standard output file 
stderr standard error file 

A constant NULL (0) designates a nonexistent pointer. 

An integer-constant EOF (-1) is returned upon end-of-file or error by most 
integer functions that deal v^ith streams (see the individual descriptions for 
details). 

An integer constant BUFSIZ specifies the size of the buffers used by the par- 
ticular implementation. 

Any program that uses this package must include the header file of per- 
tinent macro definitions, as follows: 

#include <stdio.h> 

The functions and constants mentioned in the entries of sub-class 38 of this 
manual are declared in that header file and need no further declaration. 
The constants and the foUov^ng "functions" are implemented as macros 
(redeclaration of these names is perilous): getc, getchar, putc, putchar, fer- 
ror, feof, clearerr, and fileno. 

Output streams, with the exception of the standard error stream stderr, are 
by default buffered if the output refers to a file, and line-buffered if the out- 
put refers to a terminal. The standard error output stream stderr is by 
default unbuffered, but use of f reopen [see fopen{33)\ will cause it to become 
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buffered or line-buffered. When an output stream is unbuffered, informa- 
tion is queued for writing on the destination file or terminal as soon as writ- 
ten. When it is buffered, many characters are saved up and written as a 
block. When it is line-buffered, each line of output is queued for writing on 
the destination terminal as soon as the line is completed (that is, as soon as 
a new-line character is written or terminal input is requested). The 
sethuf{3S) or setvbufQ functions in setbuf{3S) may be used to change the 
stream's buffering strategy. 

SEE ALSO 

open(2), close(2), lseek(2), pipe(2), read(2), write(2), ctermid(3S), cuserid(3S), 
fclose(3S), ferror(3S), fopen(3S), fread(3S), fseek(3S), getc(3S), gets(3S), 
popen(3S), printf(3S), putc(3S), puts(3S), scanf(3S), setbuf(3S), system(3S), 
tmpfile(3S), tmpnam(3S), ungetc(3S). 

DIAGNOSTICS 

Invalid stream pointers will usually cause grave disorder, possibly including 
program termination. Individual function descriptions describe the possible 
error conditions. 
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NAME 

stdipc: ftok - standard interprocess communication package 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ipc.h> 

key-t ftoWpath, id) 
char *path; 
char id; 

DESCRIPTION 

All interprocess communication facilities require the user to supply a key to 
be used by the msgget(2), semget{2), and shinget{2) system calls to obtain 
interprocess communication identifiers. One suggested method for forming 
a key is to use the ftok subroutine described below. Another way to com- 
pose keys is to include the project ID in the most significant byte and to use 
the remaining portion as a sequence number. There are many other ways 
to form keys, but it is necessary for each system to define standards for 
forming them. If some standard is not adhered to, it will be possible for 
unrelated processes to unintentionally interfere with each other's operation. 
Therefore, it is strongly suggested that the most significant byte of a key in 
some sense refer to a project so that keys do not conflict across a given sys- 
tem. 

Ftok returns a key based on path and id that is usable in subsequent msgget, 
semget, and shmget system calls. Path must be the path name of an existing 
file that is accessible to the process. Id is a character which uniquely identi- 
fies a project. Note that ftok will return the same key for linked files when 
called with the same id, and that it will return different keys when called 
with the same file name but different ids. 

SEE ALSO 

intro(2), msgget(2), semget(2), shmget(2). 
DIAGNOSTICS 

Ftok returns (key—t) -1 if path does not exist or if it is not accessible to the 
process. 

WARNING 

If the file whose path is passed to ftok is removed when keys still refer to 
the file, future calls to ftok with the same path and id will return an error. If 
the same file is recreated, then ftok is likely to return a different key than it 
did the original time it was called. 
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NAME 

string: strcat, strdup, stmcat, strcmp, stmcmp, strcpy, stmcpy, strlen, strchr, 
strrchr, strpbrk, strspn, strcspn, strtok - string operations 

SYNOPSIS 

#include <string.h> 
#include <8ys/t)rpes.h> 

char «strcat (si, s2) 
char *sl, *82; 

char «strdup (si) 
char *sl; 

char 'I'strncat (si, s2, n) 
char *sl, *82; 
size^t n; 

int strcmp (si, s2) 
char *sl, *s2; 

int strncmp (si, s2, n) 
char *sl, *s2; 
size_t n; 

char *strcpy (si, s2) 
char *sl, *s2; 

char I'strncpy (si, s2, n) 
char *sl, *s2; 
size_t n; 

int strlen (s) 
char *s; 

char *strchr (s, c) 
char *s; 
int c; 

char *strrchr (s, c) 
char *s; 
int c; 

char *strpbrk (si, s2) 
char *sl, *82; 

int strspn (si, s2) 
char *sl, *s2; 

int strcspn (si, s2) 
char *sl, *s2; 

char I'strtok (si, s2) 
char *sl, *s2; 
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DESCRIPTION 

The arguments si, s2, and s point to strings (arrays of characters terminated 
by a null character). The functions strcat, strncat, strcpy, and strncpy all 
alter si. These functions do not check for overflow of the array pointed to 
by si. 

Strcat appends a copy of string s2 to the end of string si. 

Strdup returns a pointer to a nevy^ string v^hich is a duplicate of the string 
pointed to by si. The space for the nev^ string is obtained using malloc{3C). 
If the new string cannot be created, null is returned. 

Strncat appends at most n characters. Each returns a pointer to the null- 
terminated result. 

Strcmp compares its arguments and returns an integer less than, equal to, or 
greater than 0, according as si is lexicographically less than, equal to, or 
greater than s2. Strncmp makes the same comparison but looks at most n 
characters. 

Strcpy copies string s2 to si, stopping after the null character has been 
copied. Strncpy copies exactly n characters, truncating s2 or adding null 
characters to si if necessary. The result will not be null-terminated if the 
length of s2 is n or more. Each function returns si. 

Strlen returns the number of characters in s, not including the terminating 
null character. 

Strchr (strrchr) returns a pointer to the first (last) occurrence of character c 
in string s, or a NULL pointer if c does not occur in the string. The null 
character terminating a string is considered to be part of the string. 

Strpbrk returns a pointer to the first occurrence in string si of any character 
from string s2, or a NULL pointer if no character from s2 exists in si. 

Strspn (strcspn) returns the length of the initial segment of string si which 
consists entirely of characters from (not from) string s2. 

Strtok considers the string si to consist of a sequence of zero or more text 
tokens separated by spans of one or more characters from the separator 
string s2. The first call (with pointer si specified) returns a pointer to the 
first character of the first token, and will have vmtten a null character into 
si immediately following the returned token. The function keeps track of its 
position in the string between separate calls, so that subsequent calls (which 
must be made with the first argument a NULL pointer) will work through 
the string si immediately following that token. In this way subsequent calls 
will work through the string si until no tokens remain. The separator 
string s2 may be different from call to call. When no token remains in si, a 
NULL pointer is returned. 

For user convenience, all these functions are declared in the optional 
<string.h> header file. 

SEE ALSO 

malloc(3C), malloc(3X). 
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CAVEATS 

Strcmp and strncmp are implemented by using the most natural character 
comparison on the machine. Thus the sign of the value returned when one 
of the characters has its high-order bit set is not the same in all implementa- 
tions and should not be relied upon. 

Character movement is performed differently in different implementations. 
Thus overlapping moves may yield surprises. 
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NAME 

strtod, atof - convert string to double-precision number 

SYNOPSIS 

double strtod (str, ptr) 
char *8tr, **ptr; 

double atof (str) 
char *str; 

DESCRIPTION 

The strtod function returns as a double-precision floating-point number the 
value represented by the character string pointed to by str. The string is 
scanned up to the first unrecognized character. 

The strtod function recognizes an optional string of "white-space" characters 
[as defined by isspace in ctype {3C)l then an optional sign, then a string of 
digits optionally containing a decimal point, then an optional e or E fol- 
lowed by an optional sign or space, followed by an integer. 

If the value of ptr is not (char **)null, a pointer to the character terminat- 
ing the scan is returned in the location pointed to by ptr. If no number can 
be formed, *ptr is set to str, and zero is returned. 

Atofistr) is equivalent to strtod(str, (char **)NULL). 

SEE ALSO 

ctype(3C), scanf(3S), strtol(3C). 

DIAGNOSTICS 

If the correct value would cause overflow, ±HUGE (as defined in <math.h>) 
is returned (according to the sign of the value), and ermo is set to erange. 
If the correct value would cause underflow, zero is returned and ermo is set 

to ERANGE. 
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NAME 

strtol, atol, atoi - convert string to integer 

SYNOPSIS 

long strtol (str, ptr, base) 
char *str, **ptr; 
int base; 

long atol (str) 
char *str; 

int atoi (str) 
char *str; 

DESCRIPTION 

The strtol function returns as a long integer the value represented by the 
character string pointed to by str. The string is scanned up to the first char- 
acter inconsistent vydth the base. Leading "white-space" characters [as 
defined by isspace in ctype{3C)] are ignored. 

If the value of ptr is not (char **)NULL, a pointer to the character terminat- 
ing the scan is returned in the location pointed to by ptr. If no integer can 
be formed, that location is set to str, and zero is returned. 

If base is positive (and not greater than 36), it is used as the base for 
conversion. After an optional leading sign, leading zeros are ignored, and 
"Ox" or "OX" is ignored if base is 16. 

If base is zero, the string itself determines the base. After an optional lead- 
ing sign a leading zero indicates octal conversion, and a leading "Ox" or 
"OX" hexadecimal conversion. Othenvise, decimal conversion is used. 

Truncation from long to int can, of course, take place upon assignment or 
by an explicit cast. 

Atol(str) is equivalent to strtol(str, (char **)NULU 10), 
Atoi(str) is equivalent to (int) strtoKstr, (char ^*)NULL, 10). 
SEE ALSO 

ctype(3C), scanf(3S), strtod(3C). 

DIAGNOSTICS 

If the argument ptr is a null-pointer, the function strtol will return the value 
of the string str as a long integer. 

If the argument ptr is not NULL, the function strtol will return the value of 
the string str as a long integer, and a pointer to the character terminating 
the scan will be returned in the location pointed to by ptr. 

If no integer can be formed, that location is set to the argument str and the 
function strtol returns 0. 

CAVEAT 

Overflow conditions are ignored. 
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NAME 

swab - swap bytes 

SYNOPSIS 

void swab (from, to, nbytes) 
char *from, *to; 
int nbytes; 

DESCRIPTION 

The swab function copies nbytes bytes pointed to by from to the array 
pointed to by to, exchanging adjacent even and odd bytes. Nbytes should 
be even and non-negative. If nbytes is odd and positive, swab uses nbytes-l 
instead. If nbytes is negative, swab does nothing. 
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NAME 

system - issue a shell command 

SYNOPSIS 

#include <stdio.h> 

int system (string) 
char ^string; 

DESCRIPTION 

The system function causes the string to be given to sh{l) as input, as if the 
string had been typed as a command at a terminal. The current process 
waits until the shell has completed, then returns the exit status of the shell. 

FILES 

/bin/sh 

SEE ALSO 

exec(2). 

sh(l) in the User's/System Administrator's Reference Manual. 
DIAGNOSTICS 

The system function forks to create a child process that in turn exec's 
/bin/sh in order to execute string. If the fork or exec fails, system returns a 
negative value and sets errno. 
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NAME 

tarn - TAM transition libraries 

SYNOPSIS 

#include <tam.h> 

cc -I /usr/indude/tam [ flags ] files -Itam -Icurses [ libraries ] 
DESCRIPTION 

These routines are used to convert existing TAM programs such that they 
run on the 3B processor line using any terminal supported by curses, the 
low-level ETI library. Once you change a TAM program to remove 
machine-specific code, you then recompile it #includeing the standard 
TAM header file tam.h and link it with the TAM transition and curses 
libraries. 

FUNCTIONS 

The following is a list of TAM routines supplied in the transition library. 
Those routines marked with a dagger (t) are macros and don't return any 
value. For a complete description of each routine, see the UNIX System V 
User's Manual under the entries indicated. 

addch(c)t See curses(3X) 

char c; 

addstrCs)-]- 
char *s; 

int adf-gttok (ptr, tbl) See paste(3T) 

char *ptr; 

struct s_kwtbl *tbl; 

char *ad£-.gtwrd (sptr, dptr) 
char *sptr, *dptr; 

char *adf— gtxcd (sptr, dptr) 
char *sptr, *dptr; 

int attrof£(attrs) See curses{3X) 

long attrs; 

int attron(attrs) 
long attrs; 

int baudrateO 

int beepO 

int cbreakO 

int clearO 

clearok(dummy, dummy)! 
int dummy; 

int clrtobotO 

int clrtoeolO 

int delchO 

int deletelnO 
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int echoO 
int endwinO 
eraseOj- 

int exhelp (hfile, htitle) 
char *hfile, *htitle; 

int BxtermO 

flashOt 

int flushinpO 

int form (form, op) 
form_t *form; 
int op; 

int getchO 



See curses(3X) 



See form{3T) 



See curses{3X) 



See message{3T) 



getyx(win, r, c)t 
int win, r, c; 

int initscrO 

int insch(ch) 
char ch; 

int insertlnO 

int iswindO See rAM(3T); always returns 

char *kcodemap (code) See curses{3X) 

unsigned char code; 

int keypad (dummy, flag) 
int dummy, flag; 

leaveok(dummy, dummy)-f 
int dummy; 

int menu (menu, op) See menu(3T) 

menu_t *menu; 
int op; 

int message (mtype, hfile, htitle, format [, arg ...] See message{3T) 
int mtype; 

char *hfile, ♦htitle, *format; 

move(r, c)t See curses{3X) 

int r, c; 

mvaddch(r, c, ch)| 
int r, c; 
char ch; 

mvaddstr(r, c, s)t 
int r, c; 
char * s; 

unsigned long mvinch(r, c) 
int r, c; 
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mot 

int nocbreakO 

int nodelay(duminy, bool) 

int dummy, bool; 

int noechoO 
nonlOt 



NOT SUPPORTED; 

See ETI Release Notes for a workaround 



int pb_check (stream) 



NOT SUPPORTED; 

See ETI Release Notes for a workaround 
See paste(3T) 



FILE *stream; 

int pb_empty (stream) 
FILE *stream; 

int pb^buf (ptr, n, fn, stream) 

char *ptr; 

int n; 

int (*fn) 0; 

FILE *stream; 

char *pb_gets (ptr, n, stream) 
char *ptr; 
int n; 

FILE *stream; 

char *pb_iiame() 

FILE *pb-.openO 

int pb_puts (ptr, stream) 
char *ptr; 
FILE *stream; 

int pb— seek (stream) 
FILE *stream; 

int pb— weof (stream) 
FILE *stream; 

int printw (fmt[, argl ... argn]) See curses{3X) 

char *fmt; 

refreshOf 

int resettermO 

int resettyO 

int savettyO 

int track (w, trk, op, butptr, whyptr) See wgetcQ 
int w, op, *butptr, *whyptr; 
track-t *trk; 

int wcmd (wn, cp) See tam(3T), Outputs a null-terminated 

short wn; string to the entry/echo line, 

char *cp; 

int wcreate (row, col, height, width, flags) Creates a window. 
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short row, col, height, widths- 
unsigned short flags; 

int wdelete (wn) 
short wn; 

void wexit(ret) 
int ret; 

int wgetc (wn) 
short wn; 

int wgetmouse (wn, ms) 
short wn; 
struct umdata '^ms; 

int wgetpos (wn, rowp, colp) 
short wn; 
int ♦rowp, *colp; 

int wgetselO 

int wgetstat (wn, wstatp) 
short wn; 
WSTAT *wstatp; 

int wgoto (wn, row, col) 
short wn, row, col; 

void wicoff (wn, row, col, icp) 
short wn, row, con- 
struct icon ♦icp; 

void wicon (wn, row, col, icp) 
short wn, row, col; 
struct icon ♦icp; 

int wind (type, height, width, flags, pfont)See wind{3T) 
int type, height, width; 
short flags; 
char ♦pfontf]; 

void winitO 



Deletes the specified window. 
See TAM(3T) 

no-op; returns 0. 



Gets the current position (row, column) 
of the cursor in the specified 
window (wn). 

Returns the currently selected window. 

Returns the information in WSTAT for a 
window. 



Moves the window's cursor to a specified 
row, column. 

no-op. returns 0. 



no-op. returns 0. 



int wlabel (wn, cp) 
short wn; 
char ♦cp; 

int wndelay (wn, bool) 
int wn, bool; 

void wnl (wn, flag) 
short wn; 
int flag; 

int wpostwaitO 
int wprexecO 



Sets up the process for window access. 
See TAM(3T). 

Outputs a null-terminated string to the 
window label area. 



NOT SUPPORTED; 

See ETI Release Notes for workaround. 

Reverses the effects of wprexecQ. 

Performs the appropriate actions for 
passing a window to a child process. 
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Outputs a null-terminated string to the 
prompt line. 

Outputs a character to a window (wn). 
Outputs a character string to a window. 

NOT SUPPORTED. 



int wprintf (wn, fmt[, argl ... argn]) 
short wn; 
char *fmt; 

int wprompt (wn, cp) 
short wn; 

char *cp; 

int wputc (wn, c) 
short wn; 
char c; 

int wputs (wn, cp) 
short wn; 
char *cp; 

int wrastop (w, srcbase, srcwidth, dstbase, 
dstwidth, srcx, srcy, dstx, 
dsty, width, height, srcop, 
dstop, pattern) 

int w; 

unsigned short ♦srcbase, *dstbase, *pattern; 
unsigned short srcwidth, dswidth, width, height; 
unsigned short srcx, srcy, dstx, dsty; 
char srcop, dstop; 

int wreadmouse (wn, xp, yp, bp, rp) no-op; returns 0. 
short wn; 

int ♦xp, ♦yp, ♦bp, ♦rp; 

int wrefresh (wn) 
short wn; 

int wselect (wn) 
short wn; 

int wsetmouse (wn, ms) 
short wn; 
struct umdata ♦ms; 

int wsetstat (wn, wstatp) 
short wn; 
WSTAT ♦wstatp; 

int wslk (wn, 0, slongl, slong2, sshort) 
short wn; 
char ♦slongl, ♦slong2, ♦sshort; 

int wslk (wn, kn, Uabel, slabel) Writes a null-terminated string to a screen 

labeled key. The alternate form writes all 
the screen labeled keys at once, which is more 
efficient. 

NOT SUPPORTED. 



Flushes all output to the window. 

Selects the specified window as the 
current or active one. 

no-op; returns 0. 



Sets the status for a window. 



Writes a null-terminated string 
to a set of screen labeled keys. 



short wn, kn; 
char ♦Uabel, ♦slabel; 



int wuser (wn, cp) 
short wn; 
char ♦cp; 
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SEE ALSO 

curses(3X), field(3X), fieldtype(3X), fonn(3X), item{3X), menu(3X), panel(3X). 
The UNIX System V ETI Programmer's Guide, 
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NAME 

tmpfile - create a temporary file 

SYNOPSIS 

#include <stdio.h> 

FILE *tmpfile () 

DESCRIPTION 

The tmpfile function creates a temporary file using a name generated by 
tmpnam(3S), and returns a corresponding FILE pointer. If the file cannot be 
opened, a NULL pointer is returned. The file will automatically be deleted 
when the process using it terminates. The file is opened for update 
("w+ "). 
SEE ALSO 

creat(2), unlink(2), fopen(3S), mktemp(3C), stdio(3S), tmpnam(3S). 
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NAME 



tmpnam, tempnam - create a name for a temporary file 

SYNOPSIS 

#include <8tdio.h> 

char ♦tmpnam (s) 
char *s; 

char I'tempnam (dir, pfx) 
char *dir, *pfx; 

DESCRIPTION 

These functions generate file names that can safely be used for a 



defined as P_tmpdir in the <stdio.h> header file. If s is NULL, tmpnam 
leaves its result in an internal static area and returns a pointer to that area. 
The next call to tmpnam will destroy the contents of the area. If s is not 
NULL, it is assumed to be the address of an array of at least L— tmpnam 
bytes, where L_tmpnam is a constant defined in <stdio.h>; tmpnam places 
its result in that array and returns s. 

Tempnam allows the user to control the choice of a directory. The argument 
dir points to the name of the directory in which the file is to be created. If 
dir is NULL or points to a string that is not a name for an appropriate direc- 
tory, the path-prefix defined as P_tmpdir in the <stdio.h> header file is 
used. If that directory is not accessible, /tmp will be used as a last resort. 
This entire sequence can be up-staged by providing an environment variable 
TMPDIR in the user's environment, whose value is the name of the desired 
temporary-file directory. 

Many applications prefer their temporary files to have certain favorite initial 
letter sequences in their names. Use the pfx argument for this. This argu- 
ment may be NULL or point to a string of up to five characters to be used as 
the first few characters of the temporary-file name. 

Tempnam uses malloc{3C) to get space for the constructed file name and 
returns a pointer to this area. Thus, any pointer value returned from temp- 
nam may serve as an argument to free [see malloc{3C)], If tempnam cannot 
return the expected resuh for any reason, i.e., malloc(3C) failed, or none of 
the above mentioned attempts to find an appropriate directory was success- 
ful, a NULL pointer will be returned. 

SEE ALSO 

creat(2), unlink(2), fopen(3S), malloc(3C), mktemp(3C), tmpfile(3S). 

NOTES 

These functions generate a different file name each time they are called. 

Files created using these functions and either fopen{3S) or creat(2) are tem- 
porary only in the sense that they reside in a directory intended for tem- 
porary use, and their names are unique. It is the user's responsibility to use 
unlink (2) to remove the file when its use is ended. 
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CAVEATS ^ 

If called more than 17,576 times in a single process, these functions will 
start recycling previously used names. 

Between the time a file name is created and the file is opened, it is possible 
for some other process to create a file with the same name. This can never 
happen if that other process is using these functions or mktemp, and the file 
names are chosen to render duplication by other means unlikely. 
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NAME 

trig: sin, cos, tan, asin, acos, atan, atan2 - trigonometric functions 
SYNOPSIS 

#include <math.h> 

double sin (x) 
double x; 

double cos (x) 
double x; 

double tan (x) 
double x; 

double asin (x) 
double x; 

double acos (x) 
double x; 

double atan (x) 
double x; 

double atan2 (y, x) 
double y, x; 

DESCRIPTION 

The sin, cos, and tan functions return respectively the sine, cosine, and 
tangent of their argument, x, measured in radians. 

Asin returns the arcsine of x, in the range [-7r/2,7r/2]. 

Acos returns the arccosine of x, in the range [0,7r]. 

Atan returns the arctangent of x, in the range [-w/2,ir/2]. 

Atanl returns the arctangent of y/x, in the range (-7r,7r], using the signs of 
both arguments to determine the quadrant of the return value. 
SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

Sin, cos, and tan lose accuracy when their argument is far from zero. For 
arguments sufficiently large, these functions return zero when there would 
otherwise be a complete loss of significance. In this case a message indicat- 
ing TLOSS error is printed on the standard error output. For less extreme 
arguments causing partial loss of significance, a PLOSS error is generated but 
no message is printed. In both cases, ermo is set to ERANGE. 

If the magnitude of the argument of asin or acos is greater than one, or if 
both arguments of atanl are zero, zero is returned and ermo is set to EDOM. 
In addition, a message indicating DOMAIN error is printed on the standard 
error output. 

These error-handling procedures may be changed with the function 
matherr{3M). 
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NAME 

tsearch, tfind, tdelete, twalk - manage binary search trees 

SYNOPSIS 

#include <search.h> 

char *tsearch ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

char *tfind ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

char *tdelete ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

void twalk ((char *) root, action) 
void (*action)( ); 

DESCRIPTION 

The tsearch, tfind, tdelete, and twalk functions are routines for manipulating 
binary search trees. They are generalized from Knuth (6.2.2) Algorithms T 
and D. All comparisons are done with a user-supplied routine. This rou- 
tine is called with two arguments, the pointers to the elements being com- 
pared. It returns an integer less than, equal to, or greater than 0, according 
to whether the first argument is to be considered less than, equal to, or 
greater than the second argument. The comparison function need not corn- 
pare every byte, so arbitrary data may be contained in the elements in addi- 
tion to the values being compared. 

The tsearch function is used to build and access the tree. Key is a pointer 
to a datum to be accessed or stored. If there is a datum in the tree equal to 
*key (the value pointed to by key), a pointer to this found datum is 
returned. Otherwise, *key is inserted, and a pointer to it returned. Only 
pointers are copied, so the calling routine must store the data. Rootp points 
to a variable that points to the root of the tree. A NULL value for the vari- 
able pointed to by rootp denotes an empty tree; in this case, the variable 
will be set to point to the datum which will be at the root of the new tree. 

Like tsearch, tfind will search for a datum in the tree, returning a pointer to 
it if found. However, if it is not found, tfind will return a NULL pointer. 
The arguments for tfind are the same as for tsearch. 

Tdelete deletes a node from a binary search tree. The arguments are the 
same as for tsearch. The variable pointed to by rootp will be changed if the 
deleted node was the root of the tree. Tdelete returns a pointer to the 
parent of the deleted node, or a NULL pointer if the node is not found. 

Twalk traverses a binary search tree. Root is the root of the tree to be 
traversed. (Any node in a tree may be used as the root for a walk below 
that node.) Action is the name of a routine to be invoked at each node. 
This routine is, in turn, called with three arguments. The first argument is 
the address of the node being visited. The second argument is a value from 
an enumeration data type typedef enum { preorder, postorder, endorder, leaf } 
VISIT; (defined in the <search.h> header file), depending on whether this is 
the first, second, or third time that the node has been visited (during a 
depth-first, left-to-right traversal of the tree), or whether the node is a leaf. 
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The third argument is the level of the node in the tree, with the root beine 
level zero. ° 

The pointers to the key and the root of the tree should be of type pointer- 
to-element, and cast to type pointer-to-character. Similarly, although 
declared as type pointer-to-character, the value returned should be cast into 
type pointer-to-element. 

EXAMPLE 

The following code reads in strings and stores structures containing a 
pomter to each string and a count of its length. It then walks the tree 
pnnting out the stored strings and their lengths in alphabetical order. 

#include <search.h> 
#include <stdio.h> 

struct node { /♦ pointers to these are stored in the tree */ 
char *string; 
int length; 

>; 

char string_space[ 10000]; /♦ space to store strings */ 

struct node nodes[500]; /* nodes to store */ 

struct node *root = null; /♦ this points to the root */ 



main( ) 
{ 



} 

/♦ 



char ♦strptr = string_space ; 
struct node *nodeptr = nodes; 
void print_node( ), twalk( ); 
int i = 0, node_compare( ); 

while (gets(strptr ) != null i++ < 500) { 
/* set node ♦/ 
nodeptr— >string = strptr; 
nodeptr->length = strlen ( strptr ) ; 
/* put node into the tree */ 

(void) tsearch( (char *)nodeptr, (char **) &root , 

node_compare ) ; 
/♦ adjust pointers, so we don't overwrite tree * 
strptr += nodeptr->length + 1; 
nodeptr++ ; 

} 

twalk((char ♦)root, print_node); 



This routine compares two nodes, based on an 
alphabetical ordering of the string field. 

*/ 

int 

node_compare(node1 , node2) 
char ♦nodel, *node2; 
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{ 

return strcmp ((( struct node *) node 1 ) — >str ing , 
((struct node *) node2 )->string ) ; 

} 

/* 

This routine prints out a node, the first time 
twalk encounters it. 

♦/ 

void 

print_node(node , order, level) 

char **node ; 

VISIT order; 

int level; 

{ 

if (order == preorder II order == leaf) { 

(void)printf( "string = %20s, length = %d\n" , 
(♦((struct node **)node ) ) ->string , 
(♦((struct node **)node ) ) ->length ) ; 

} 

} 

SEE ALSO 

bsearch(3C), hsearch(3C), lsearch(3C). 

DIAGNOSTICS 

A NULL pointer is returned by tsearch if there is not enough space available 
to create a new node. 

A NULL pointer is returned by tfind and tdelete if rootp is NULL on entry. 
If the datum is found, both tsearch and tfind return a pointer to it. If not, 
tfind returns NULL, and tsearch returns a pointer to the inserted item. 

WARNINGS 

The root argument to twalk is one level of indirection less than the rootp 
arguments to tsearch and tdelete. 

There are two nomenclatures used to refer to the order in which tree nodes 
are visited. The tsearch function uses preorder, postorder, and endorder to 
respectively refer to visiting a node before any of its children, after its left 
child and before its right, and after both its children. The alternate nomen- 
clature uses preorder, inorder, and postorder to refer to the same visits, 
which could result in some confusion over the meaning of postorder. 

CAVEAT 

If the calling function alters the pointer to the root, results are unpredict- 
able. 
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NAME 

ttjniame, isatty - find name of a terminal 
SYNOPSIS 

char «ttyname (fildes) 
int fildes; 

int isatty (fildes) 
int fildes; 

DESCRIPTION 

The ttyname function returns a pointer to a string containing the null- 
terminated path name of the terminal device associated with file descriptor 
fildes. 

Isatty returns 1 if fildes is associated with a terminal device, otherwise. 

FILES 

/dev/* 
DIAGNOSTICS 

The ttyname function returns a NULL pointer if fildes does not describe a 
terminal device in directory /dev. 

CAVEAT 

The return value points to static data whose content is overwritten by each 
call. 
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NAME 

ttyslot - find the slot in the utmp file of the current user 

SYNOPSIS 

int ttyslot ( ) 

DESCRIPTION 

The ttyslot function returns the index of the current user's entry in the 
/etc/utmp file. This is accomplished by actually scanning the file 
/etc/inittab for the name of the terminal associated with the standard 
input, the standard output, or the error output (0, 1 or 2). 

HLES 

/etc/inittab 
/etc/utmp 

SEE ALSO 

getut(3C), ttyname(3C). 

DIAGNOSTICS 

A value of is returned if an error was encountered while searching for the 
terminal name or if none of the above file descriptors is associated with a 
terminal device. 
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NAME 

t_accept - accept a connect request 

SYNOPSIS 

#include <tiuser.h> 

int t_accept(fd, resfd, call) 

int fd; 

int resfd; 

struct t_call *call; 

DESCRIPTION 

This function is issued by a transport user to accept a connect request. Fd 
identifies the local transport endpoint where the connect indication arrived, 
resfd specifies the local transport endpoint where the connection is to be 
established, and call contains information required by the transport provider 
to complete the connection. Call points to a t^call structure which contains 
the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro{3). In call addr is the address of the caller, opt 
indicates any protocol-specific parameters associated with the connection, 
udata points to any user data to be returned to the caller, and sequence is the 
value returned by t^listen that uniquely associates the response with a pre- 
viously received connect indication. 

A transport user may accept a connection on either the same, or on a dif- 
ferent, local transport endpoint than the one on which the connect indica- 
tion arrived. If the same endpoint is specified (i.e., resfd=fd), the connection 
can be accepted unless the following condition is true: The user has 
received other indications on that endpoint but has not responded to them 
(with t^ccept or t^nddis). For this condition, t-accept will fail and set 
t^ermo to TBADF. 

If a different transport endpoint is specified {resfdl=fd), the endpoint must 
be bound to a protocol address and must be in the T_IDLE state [see 
t-.getstate{3N)] before the t^accept is issued. 

For both types of endpoints, t^ccept will fail and set t-.ermo to TLOOK if 
there are indications (e.g., a connect or disconnect) waiting to be received 
on that endpoint. 

The values of parameters specified by opt and the syntax of those values are 
protocol-specific. The udata argument enables the called transport user to 
send user data to the caller and the amount of user data must not exceed 
the limits supported by the transport provider as returned by t^open or 
t-getinfo. If the len [see netbuf in intro(3)] field of udata is zero, no data will 
be sent to the caller. 
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On failure, t—ermo may be set to one of the following: 



[TBADF] 

[TOUTSTATE] 

[TACCES] 

[TBADOPT] 

[TBADDATA] 

[TBADSEQ] 
[TLOOK] 

[TNOTSUPPORT] 
[TSYSERR] 



The specified file descriptor does not refer to a trans- 
port endpoint, or the user is illegally accepting a con- 
nection on the same transport endpoint on which the 
connect indication arrived. 

The function was issued in the wrong sequence on the 
transport endpoint referenced by fd, or the transport 
endpoint referred to by resfd is not in the T_IDLE state. 

The user does not have permission to accept a connec- 
tion on the responding transport endpoint or use the 
specified options. 

The specified options were in an incorrect format or 
contained illegal information. 

The amount of user data specified was not within the 
bounds allowed by the transport provider. 

An invalid sequence number was specified. 

An asynchronous event has occurred on the transport 
endpoint referenced by fd and requires immediate 
attention. 

This function is not supported by the underlying trans- 
port provider. 

A system error has occurred during execution of this 
function. 



SEE ALSO 

intro(3), t_connect(3N), t_getstate(3N), t_listen(3N), t_open(3N), 
t__j:cvconnect(3N). 

Programmers Guide. 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and t^ermo is set to indicate the error. 
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NAME 

t_alloc - allocate a library structure 

SYNOPSIS 

#include <tiuser.h> 

char ♦t_alloc(fd, struct_type, fields) 
int fd; 

int struct—type; 
int fields; 

DESCRIPTION 

The t^alloc function dynamically allocates memory for the various transport 
function argument structures as specified below. This function will allocate 
memory for the specified structure, and will also allocate memory for 
buffers referenced by the structure. 

The structure to allocate is specified by struct^type, and can be one of the 
following: 

T_BIND struct t_bind 

T_CALL struct t_call 

T_OPTMGMT struct t_optmgmt 
T—DIS struct t_discon 

T_UNITDATA struct t__unitdata 
T_UDERROR struct t_uderr 
T_INFO struct t_info 

where each of these structures may subsequently be used as an argument to 
one or more transport functions. 

Each of the above structures, except T_INFO, contains at least one field of 
type struct netbuf. Netbuf is described in intro{3). For each field of this 
type, the user may specify that the buffer for that field should be allocated 
as well. The fields argument specifies this option, where the argument is 
the bitwise-OR of any of the following: 

T_ADDR The addr field of the t^bind, t-call, t^unitdata, or t-uderr struc- 
tures. 

T_OPT The opt field of the t^optmgmt, t^call, t^unitdata, or t-.uderr 
structures. 

T_UDATA The udata field of the t-call, t-discon, or t-unitdata structures. 
T_ALL All relevant fields of the given structure. 

For each field specified in fields, t^alloc will allocate memory for the buffer 
associated with the field, and initialize the buf pointer and maxlen [see net- 
buf in intro{3) for description of buf and maxlen] field accordingly. The 
length of the buffer allocated will be based on the same size information 
that is returned to the user on t^open and t-getinfo. Thus, fd must refer to 
the transport endpoint through which the newly allocated structure will be 
passed, so that the appropriate size information can be accessed. If the size 



- 1 - 



T__ALLOC(3N) 



(Networking Support Utilities) 



T_ALLOC(3N) 



value associated with any specified field is -1 or -2 (see t—open or 
t^getinfo), t— alloc will be uiiable to determine the size of the buffer to allo- 
cate and will fail, setting t^ermo to TSYSERR and ermo to EINVAL. For any 
field not specified in fields, buf will be set to NULL and maxlen will be set to 
zero. 

Use of t-alloc to allocate structures will help ensure the compatibility of 
user programs with future releases of the transport interface. 

On failure, t—errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

intro(3), t_free(3N), t_getinfo(3N), t__open(3N). 
Programmer's Guide, 
DIAGNOSTICS 

On successful completion, t-dloc returns a pointer to the newly allocated 
structure. On failure, NULL is returned. 
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NAME 

t_bind - bind an address to a transport endpoint 
SYNOPSIS 

#include <tiuser.h> 

int t-bind(fd, req, ret) 
int fd; 

struct t— bind *req; 
struct t-.bind *ret; 

DESCRIPTION 

This function associates a protocol address with the transport endpoint 
specified by fd and activates that transport endpoint. In connection mode, 
the transport provider may begin accepting or requesting connections on the 
transport endpoint. In connectionless mode, the transport user may send or 
receive data units through the transport endpoint. 

The req and ret arguments point to a t-bind structure containing the follow- 
ing members: 

struct netbuf addr; 
unsigned qlen; 

Netbuf is described in intro{3). The addr field of the t-.bind structure speci- 
fies a protocol address and the qlen field is used to indicate the maximum 
number of outstanding connect indications. 

Req is used to request that an address, represented by the netbuf structure, 
be bound to the given transport endpoint. Len [see netbuf in intro{3)) also 
for buf and maxlen] specifies the number of bytes in the address and buf 
points to the address buffer. Maxlen has no meaning for the req argument. 
On return, ret contains the address that the transport provider actually 
bound to the transport endpoint; this may be different from the address 
specified by the user in req. In ret, the user specifies maxlen which is the 
maximum size of the address buffer and buf which points to the buffer 
where the address is to be placed. On return, len specifies the number of 
bytes in the bound address and buf points to the bound address. If maxlen 
is not large enough to hold the returned address, an error will result. 

If the requested address is not available, or if no address is specified in req 
(the len field of addr in req is zero) the transport provider will assign an 
appropriate address to be bound, and will return that address in the addr 
field of ret. The user can compare the addresses in req and ret to determine 
whether the transport provider bound the transport endpoint to a different 
address than that requested. 

Req may be NULL if the user does not wish to specify an address to be 
bound. Here, the value of qlen is assumed to be zero, and the transport 
provider must assign an address to the transport endpoint. Similarly, ret 
may be NULL if the user does not care what address was bound by the pro- 
vider and is not interested in the negotiated value of qlen. It is valid to set 
req and ret to NULL for the same call, in which case the provider chooses 
the address to bind to the transport endpoint and does not return that 
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information to the user. 

The qlen field has meaning only when initializing a connection-mode ser- 
vice. It specifies the number of outstanding connect indications the trans- 
port provider should support for the given transport endpoint. An out- 
standing connect indication is one that has been passed to the transport user 
by the transport provider. A value of qlen greater than zero is only mean- 
ingful when issued by a passive transport user that expects other users to 
call it. The value of qlen will be negotiated by the transport provider and 
may be changed if the transport provider cannot support the specified 
number of outstanding connect indications. On return, the qlen field in ret 
will contain the negotiated value. 

This function allows more than one transport endpoint to be bound to the 
same protocol address (however, the transport provider must support this 
capability also), but it is not allowable to bind more than one protocol 
address to the same transport endpoint. If a user binds more than one 
transport endpoint to the same protocol address, only one endpoint can be 
used to listen for connect indications associated with that protocol address. 
In other words, only one t—bind for a given protocol address may specify a 
value of qlen greater than zero. In this way, the transport provider can 
identify which transport endpoint should be notified of an incoming connect 
indication. If a user attempts to bind a protocol address to a second trans- 
port endpoint with a value of qlen greater than zero, the transport provider 
will assign another address to be bound to that endpoint. If a user accepts a 
connection on the transport endpoint that is being used as the listening end- 
point, the bound protocol address will be found to be busy for the duration 
of that connection. No other transport endpoints may be bound for listen- 
ing while that initial listening endpoint is in the data transfer phase. This 
will prevent more than one transport endpoint bound to the same protocol 
address from accepting connect indications. 

On failure, t^ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a trans- 

port endpoint. 

[TOUTSTATE] The function was issued in the wrong sequence. 

[TBADADDR] The specified protocol address was in an incorrect for- 

mat or contained illegal information. 

[TNOADDR] The transport provider could not allocate an address. 

[TACCES] The user does not have permission to use the specified 

address. 

[TBUFOVFLW] The number of bytes allowed for an incoming argu- 

ment is not sufficient to store the value of that argu- 
ment. The provider's state will change to T_IDLE and 
the information to be returned in ret will be discarded. 

[TSYSERR] A system error has occurred during execution of this 

function. 
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SEE ALSO 

intro(3), t_open(3N), t_optmgmt(3N), t-unbind(3N). 
Programmefs Guide, 
DIAGNOSTICS 

The t—bind function returns on success and -1 on failure, and t^errno is 
set to indicate the error. 
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NAME 

t__close - close a transport endpoint 

SYNOPSIS 

#include <tiuser.h> 

int t_close(fd) 
int fd; 

DESCRIPTION 

The t—close function informs the transport provider that the user is finished 
with the transport endpoint specified by fd, and frees any local library 
resources associated with the endpoint. In addition, t— close closes the file 
associated with the transport endpoint. 

The close function should be called from the T_UNBND state [see 
t—getstate (3N)]. However, this function does not check state information, so 
it may be called from any state to close a transport endpoint. If this occurs, 
the local library resources associated with the endpoint will be freed 
automatically. In addition, close(2) will be issued for that file descriptor; the 
close will be abortive if no other process has that file open, and will break 
any transport connection that may be associated with that endpoint. 

On failure, t^ermo may be set to the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

SEE ALSO 

t_getstate(3N), t_open(3N), t_unbind(3N). 
Programmer's Guide. 
DIAGNOSTICS 

The t^close function returns on success and -1 on failure, and t—errno is 
set to indicate the error. 
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NAME 

t_connect - establish a connection with another transport user 

SYNOPSIS 

#include <tiuser.h> 

int t_connect(fd, sndcall, rcvcall) 
int fd; 

struct t_call *sndcall; 
struct t_call *rcvcall; 

DESCRIPTION 

This function enables a transport user to request a connection to the speci- 
fied destination transport user. Fd identifies the local transport endpoint 
where communication will be established, while sndcall and rcvcall point to 
a t—call structure which contains the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Sndcall specifies information needed by the transport provider to establish a 
connection, and rcvcall specifies information that is associated with the 
newly established connection. 

Netbuf is described in intro{3). In sndcall, addr specifies the protocol address 
of the destination transport user, opt presents any protocol-specific informa- 
tion that might be needed by the transport provider, udata points to 
optional user data that may be passed to the destination transport user dur- 
ing connection establishment, and sequence has no meaning for this func- 
tion. 

On return in rcvcall, addr returns the protocol address associated with the 
responding transport endpoint; opt presents any protocol-specific informa- 
tion associated with the connection; udata points to optional user data that 
may be returned by the destination transport user during connection estab- 
lishment; and sequence has no meaning for this function. 

The opt argument implies no structure on the options that may be passed to 
the transport provider. The transport provider is free to specify the struc- 
ture of any options passed to it. These options are specific to the underly- 
ing protocol of the transport provider. The user may choose not to nego- 
tiate protocol options by setting the len field of opt to zero. In this case, the 
provider may use default options. 

The udata argument enables the caller to pass user data to the destination 
transport user and receive user data from the destination user during con- 
nection establishment. However, the amount of user data must not exceed 
the linuts supported by the transport provider as returned by t—open (3N) or 
t^getinfo (3N). If the len [see netbuf in intro{3)] field of udata is zero in 
sndcall, no data v^U be sent to the destination transport user. 

On return, the addr, opt, and udata fields of rcvcall will be updated to reflect 
values associated with the connection. Thus, the maxlen [see netbuf in 
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intro{3)] field of each argument must be set before issuing this function to 
indicate the maximum size of the buffer for each. However, rcvcall may be 
NULL, in which case no information is given to the user on return from 
t^connect. 

By default, t— connect executes in synchronous mode, and will wait for the 
destination user's response before returning control to the local user. A suc- 
cessful return (i.e., return value of zero) indicates that the requested connec- 
tion has been established. However, if 0_NDELAY is set (via t—open or 
fcntl), connect executes in asynchronous mode. In this case, the call will 
not wait for the remote user's response, but will return control immediately 
to the local user and return -1 with t^ermo set to TNODATA to indicate that 
the connection has not yet been established. In this way, the function sim- 
ply initiates the connection establishment procedure by sending a connect 
request to the destination transport user. 

On failure, t^errno may be set to one of the following: 



[TBADF] 

[TOUTSTATE] 
[TNODATA] 



[TBADADDR] 



[TBADOPT] 



[TBADDATA] 



[TACCES] 



[TBUFOVFLW] 



[TLOOK] 

[TNOTSUPPORTl 
[TSYSERR] 



The specified file descriptor does not refer to a trans- 
port endpoint. 

The function was issued in the wrong sequence. 

0_NDELAY was set, so the function successfully ini- 
tiated the connection establishment procedure, but did 
not wait for a response from the remote user. 

The specified protocol address was in an incorrect for- 
mat or contained illegal information. 

The specified protocol options were in an incorrect for- 
mat or contained illegal information. 

The amount of user data specified was not within the 
bounds allowed by the transport provider. 

The user does not have permission to use the specified 
address or options. 

The number of bytes allocated for an incoming argu- 
ment is not sufficient to store the value of that argu- 
ment. If executed in synchronous mode, the provider's 
state, as seen by the user, changes to T_DATAXFER, 
and the connect indication information to be returned 
in rcvcall is discarded. 

An asynchronous event has occurred on this transport 
endpoint and requires immediate attention. 

This function is not supported by the underlying trans- 
port provider. 

A system error has occurred during execution of this 
function. 



SEE ALSO 

intro(3), t_accept(3N), t_getinfo(3N), t_listen(3N), t_open(3N), 
t_optmgmt(3N), t_rcvconnect(3N). 
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Programmer's Guide, 
DIAGNOSTICS 

The t— connect function returns on success and -1 on failure, and t—crrno 
is set to indicate the error. 
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NAME 

t_error - produce error message 

SYNOPSIS 

#include <tiuser.h> 

void t__error(errmsg) 
char *errmsg; 
extern int t_errno; 
extern char *t_errlist[]; 
extern int t-_nerr; 

DESCRIPTION 

t— error produces a message on the standard error output which describes 
the last error encountered during a call to a transport function. The argu- 
ment string errmsg is a user-supplied error message that gives context to the 
error. 

t— error prints the user-supplied error message followed by a colon and the 
standard transport function error message for the current value contained in 
t—errno. If t—ermo is TSYSERR, t-.error will also print the standard error 
message for the current value contained in errno [see intro{l)\. 

t—errlist is the array of message strings, to allow user message formatting. 
t— errno can be used as an index into this array to retrieve the error message 
string (without a terminating newline). t—tierr is the maximum index value 
for the t—.errlist array. 

t— errno is set when an error occurs and is not cleared on subsequent suc- 
cessful calls. 

EXAMPLE 

If a t-.connect function fails on transport endpoint fdl because a bad address 
was given, the following call might follow the failure: 

t__error( " t_connect failed on fd2 " ); 

The diagnostic message would print as: 

t_connect failed on fd2: Incorrect transport address format 

where "t_connect failed on fd2" tells the user which function failed on 
which transport endpoint, and "Incorrect transport address format" identi- 
fies the specific error that occurred. 

SEE ALSO 

Programmer's Guide. 
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NAME 

t__free - free a library structure 

SYNOPSIS 

#include <tiuser.h> 

int t_free(ptr, struct_type) 

char *ptr; 

int struct_type; 

DESCRIPTION 

The t--free function frees memory previously allocated by t^lloc. This 
function will free memory for the specified structure and will also free 
memory for buffers referenced by the structure. 

Ptr points to one of the six structure types described for t— alloc, and 
struct— type identifies the type of that structure which can be one of the fol- 
lowing: 

T_BIND struct t_bind 

T_CALL struct t_call 

T^OPTMGMT struct t_optmgmt 
T_DIS struct t_discon 

T-.UNITDATA struct t_unitdata 
T-UDERROR struct t__uderr 
T_JNFO struct t_info 

where each of these structures is used as an argument to one or more trans- 
port functions. 

The t—free function will check the addr, opt, and udata fields of the given 
structure (as appropriate) and free the buffers pointed to by the buf field of 
the netbuf [see intro{3)] structure. If buf is NULL, t—free will not attempt to 
free memory. After all buffers are freed, t—free will free the memory associ- 
ated with the structure pointed to by ptr. 

Undefined results will occur if ptr or any of the buf pointers points to a 
block of memory that was not previously allocated by t— alloc. 

On failure, t—ermo may be set to the following: 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

intro(3), t_alloc(3N). 

Programmer's Guide. 

DIAGNOSTICS 

The t—free function returns on success and -1 on failure, and t—ermo is set 
to indicate the error. 
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NAME 

t_getinfo - get protocol-specific service information 

SYNOPSIS 

#include <tiuser.h> 

int t— getinfo(fd, info) 
int fd; 

struct t— info *info; 
DESCRIPTION 

This function returns the current characteristics of the underlying transport 
protocol associated with file descriptor fd. The info structure is used to 
return the same information returned by t^open. This function enables a 
transport user to access this information during any phase of communica- 
tion. 

This argument points to a t—info structure which contains the following 
members: 

long addr; /* max size of the transport protocol address */ 
long options; /* max number of bytes of protocol-specific options */ 
long tsdu; /* max size of a transport service data unit (TSDU) */ 
long etsdu; /* max size of an expedited transport service data 
unit (ETSDU) */ 

long connect; /* max amount of data allowed on connection establish- 
ment 

functions */ 

long discon; /* max amount of data allowed on t^nddis and t^rcvdis 
functions */ 

long servtype; /* service type supported by the transport provider */ 
The values of the fields have the following meanings: 

addr A value greater than or equal to zero indicates the maximum 

size of a transport protocol address; a value of -1 specifies 
that there is no limit on the address size; and a value of -2 
specifies that the transport provider does not provide user 
access to transport protocol addresses. 

options A value greater than or equal to zero indicates the maximum 

number of bytes of protocol-specific options supported by 
the provider; a value of -1 specifies that there is no limit on 
the option size; and a value of -2 specifies that the transport 
provider does not support user-settable options. 

tsdu A value greater than zero specifies the maximum size of a 

transport service data unit (TSDU); a value of zero specifies 
that the transport provider does not support the concept of 
TSDU, although it does support the sending of a data stream 
with no logical boundaries preserved across a connection; a 
value of -1 specifies that there is no limit on the size of a 
TSDU; and a value of -2 specifies that the transfer of normal 
data is not supported by the transport provider. 
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etsdu A value greater than zero specifies the maximum size of an 

expedited transport service data unit (ETSDU); a value of 
zero specifies that the transport provider does not support 
the concept of ETSDU, although it does support the sending 
of an expedited data stream with no logical boundaries 
preserved across a connection; a value of -1 specifies that 
there is no limit on the size of an ETSDU; and a value of -2 
specifies that the transfer of expedited data is not supported 
by the transport provider. 

connect A value greater than or equal to zero specifies the maximum 

amount of data that may be associated with connection 
establishment functions; a value of -1 specifies that there is 
no limit on the amount of data sent during connection estab- 
lishment; and a value of -2 specifies that the transport pro- 
vider does not allow data to be sent with connection estab- 
lishment functions. 

discon A value greater than or equal to zero specifies the maximum 

amount of data that may be associated with the t^nddis and 
t^rcvdis functions; a value of -1 specifies that there is no 
limit on the amount of data sent with these abortive release 
functions; and a value of -2 specifies that the transport pro- 
vider does not allow data to be sent with the abortive 
release functions. 

serotype This field specifies the service type supported by the trans- 

port provider, as described below. 

If a transport user is concerned with protocol independence, the above sizes 
may be accessed to determine how large the buffers must be to hold each 
piece of information. Alternatively, the t— alloc function may be used to 
allocate these buffers. An error will result if a transport user exceeds the 
allowed data size on any function. The value of each field may change as a 
result of option negotiation, and t—getinfo enables a user to retrieve the 
current characteristics. 

The serotype field of info may specify one of the following values on return: 

T_COTS The transport provider supports a connection-mode service 

but does not support the optional orderly release facility. 

T_COTS_ORD The transport provider supports a connection-mode service 
with the optional orderly release facility. 

T_CLTS The transport provider supports a connectionless-mode ser- 

vice. For this service type, t^open will return -2 for etsdu, 
connect, and discon. 

On failure, t—errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 
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SEE ALSO 

t_open(3N). 

Programmefs Guide. 

DIAGNOSTICS 

The t—getinfo function returns on success and -1 on failure, and t—ermo is 
set to indicate the error. 
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NAME 

t_getstate - get the current state 

SYNOPSIS 

#include <tiu8er.h> 

int t_getstate(fd) 
int f d; 

DESCRIPTION 

The t-^getstate function returns the current state of the provider associated 
with the transport endpoint specified by fd. 

On failure, t—ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TSTATECHNG] The transport provider is undergoing a state change. 

[TSYSERR] A system error has occurred during execution of this 

function. 

SEE ALSO 

t__open(3N). 

Programmer's Guide. 

DIAGNOSTICS 

The t—getstate function returns the current state on successful completion 
and -1 on failure, and t^errno is set to indicate the error. The current state 
may be one of the following: 

T_UNBND unbound 

T_1DLE idle 

T_OUTCON outgoing connection pending 
T_INCON incoming connection pending 

T_DATAXFER data transfer 

T_OUTREL outgoing orderly release (waiting for an orderly release 
indication) 

T_INREL incoming orderly release (waiting for an orderly release 

request) 

If the provider is undergoing a state transition when t—getstate is called, the 
function will fail. 
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NAME 

t_listen - listen for a connect request 

SYNOPSIS 

#include <tiuser.h> 

int t_listen(fd, call) 
int f d; 

struct t_call *call; 
DESCRIPTION 

This function listens for a connect request from a calling transport user. Fd 
identifies the local transport endpoint where connect indications arrive, and 
on return, call contains information describing the connect indication. Call 
points to a t—call structure which contains the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro(3). In call, addr returns the protocol address of 
the calling transport user; opt returns protocol-specific parameters associated 
with the connect request; udata returns any user data sent by the caller on 
the connect request; and sequence is a number that uniquely identifies the 
returned connect indication. The value of sequence enables the user to listen 
for multiple connect indications before responding to any of them. 

Since this function returns values for the addr, opt, and udata fields of call, 
the maxlen [see netbuf in intro{3)] field of each must be set before issuing the 
t-listen to indicate the maximum size of the buffer for each. 

By default, t— listen executes in synchronous mode and waits for a connect 
indication to arrive before returning to the user. However, if 0_NDELAY is 
set (via t-.open or fcntl), t^isten executes asynchronously, reducing to a poll 
for existing connect indications. If none are available, it returns -1 and sets 
t^ermo to TNODATA. 

On failure, t^ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a trans- 

port endpoint. 

[TBUFOVFLW] The number of bytes allocated for an incoming argu- 

ment is not sufficient to store the value of that argu- 
ment. The provider's state, as seen by the user, 
changes to T_INCON, and the connect indication 
information to be returned in call is discarded. 

[TNODATA] 0_NDELAY was set, but no connect indications had 

been queued. 

[TLOOK] An asynchronous event has occurred on this transport 

endpoint and requires immediate attention. 

[TNOTSUPPORT] This function is not supported by the underlying 
transport provider. 
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[TSYSERR] A system error has occurred during execution of this 

function. 

SEE ALSO 

intro(3), t_accept(3N), t_bind(3N), t_connect(3N), t_open(3N), 
t__rcvconnect(3N). 

Programmer's Guide. 

DIAGNOSTICS 

The t^listen function returns on success and -1 on failure, and t—ermo is 
set to indicate the error. 

CAVEATS 

If a user issues t— listen in synchronous mode on a transport endpoint that 
was not bound for listening (i.e., qlen was zero on t—bind), the call will wait 
forever because no connect indications will arrive on that endpoint. 
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NAME 

t_look - look at the current event on a transport endpoint 

SYNOPSIS 

#include <tiuser.h> 

int t-Jook(fd) 
int fd; 

DESCRIPTION 

This function returns the current event on the transport endpoint specified 
by fd. This function enables a transport provider to notify a transport user 
of an asynchronous event when the user is issuing functions in synchronous 
mode. Certain events require immediate notification of the user and are 
indicated by a specific error, TLOOK, on the current or next function to be 
executed. 

This function also enables a transport user to poll a transport endpoint 
periodically for asynchronous events. 

On failure, t—ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

t_open(3N). 

Programmer's Guide. 

DIAGNOSTICS 

Upon success, t—look returns a value that indicates which of the allowable 
events has occurred, or returns zero if no event exists. One of the following 
events is returned: 

T_LISTEN connection indication received 

T_CONNECT connect confirmation received 

T_DATA normal data received 

T_EXDATA expedited data received 

T_DISCONNECT disconnect received 

T_ERROR fatal error indication 

T_UDERR datagram error indication 

T_ORDREL orderly release indication 

On failure, -1 is returned, and t—errno is set to indicate the error. 
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NAME 

t_open - establish a transport endpoint 

SYNOPSIS 

#include <tiuser.h> 



int i-open(path, oflag, info) 
char *path; 
int oflag; 

struct t_info *info; 
DESCRIPTION 

The t^open function must be called as the first step in the initialization of a 
transport endpoint. This function establishes a transport endpoint by open- 
ing a UNIX system file that identifies a particular transport provider (i.e., 
transport protocol) and returning a file descriptor that identifies that end- 
point. For example, opening the file /dev/iso^cots identifies an OSI 
connection-oriented transport layer protocol as the transport provider. 

Path points to the path name of the file to open, and oflag identifies any 
open flags [as in open{2)]. t—open returns a file descriptor that will be used 
by all subsequent functions to identify the particular local transport end- 
point. 

This function also returns various default characteristics of the underlying 
transport protocol by setting fields in the t—info structure. This argument 
points to a t^info which contains the following members: 



long addr; /* max size of the transport protocol address */ 
long options; /* max number of bytes of protocol-specific 
options */ 

long tsdu; /* max size of a transport service data unit (TSDU) */ 
long etsdu; /* max size of an expedited transport service data 

unit (ETSDU) */ 
long connect; /* max amount of data allowed on connection 

establishment functions */ 
long discon; /* max amount of data allowed on t-jsnddis and 

t—rcvdis functions */ 
long servtype; /* service type supported by the transport provider */ 

The values of the fields have the following meanings: 

A value greater than or equal to zero indicates the maximum 
size of a transport protocol address; a value of -1 specifies 
that there is no limit on the address size; and a value of -2 
specifies that the transport provider does not provide user 
access to transport protocol addresses. 

A value greater than or equal to zero indicates the maximum 
number of bytes of protocol-specific options supported by 
the provider; a value of -1 specifies that there is no limit on 
the option size; and a value of -2 specifies that the transport 
provider does not support user-settable options. 



addr 



options 
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tsdu A value greater than zero specifies the maximum size of a 

transport service data unit (TSDU); a value of zero specifies 
that the transport provider does not support the concept of 
TSDU, although it does support the sending of a data stream 
with no logical boundaries preserved across a connection; a 
value of -1 specifies that there is no limit on the size of a 
TSDU; and a value of -2 specifies that the transfer of normal 
data is not supported by the transport provider. 

etsdu A value greater than zero specifies the maximum size of an 

expedited transport service data unit (ETSDU); a value of 
zero specifies that the transport provider does not support 
the concept of ETSDU, although it does support the sending 
of an expedited data stream with no logical boundaries 
preserved across a connection; a value of -1 specifies that 
there is no limit on the size of an ETSDU; and a value of -2 
specifies that the transfer of expedited data is not supported 
by the transport provider. 

connect A value greater than or equal to zero specifies the maximum 

amount of data that may be associated with connection 
establishment functions; a value of -1 specifies that there is 
no limit on the amount of data sent during connection estab- 
lishment; and a value of -2 specifies that the transport pro- 
vider does not allow data to be sent with connection estab- 
lishment functions. 

discon A value greater than or equal to zero specifies the maximum 

amount of data that may be associated with the t^nddis and 
t^rcvdis functions; a value of -1 specifies that there is no 
limit on the amount of data sent with these abortive release 
functions; and a value of -2 specifies that the transport pro- 
vider does not allow data to be sent with the abortive 
release functions. 

serotype This field specifies the service type supported by the trans- 

port provider, as described below. 

If a transport user is concerned with protocol independence, the above sizes 
may be accessed to determine how large the buffers must be to hold each 
piece of information. Alternatively, the t— alloc function may be used to 
allocate these buffers. An error will result if a transport user exceeds the 
allowed data size on any function. 

The serotype field of info may specify one of the following values on return: 

T_-COTS The transport provider supports a connection-mode service 

but does not support the optional orderly release facility. 

T_COTS_ORD The transport provider supports a connection-mode service 
with the optional orderly release facility. 

T_CLTS The transport provider supports a connectionless-mode ser- 

vice. For this service type, t-.open will return -2 for etsdu, 
connect, and discon. 
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A single transport endpoint may support only one of the above services at 
one time. 

If info is set to ull by the transport user, no protocol information is returned 
by t^open. 

On failure, t^ermo may be set to the following: 

[TSYSERR] A system error has occurred during execution of this 

function. 

SEE ALSO 

open(2). 

Programmer's Guide. 
DIAGNOSTICS 

The t-.open function returns a valid file descriptor on success and -1 on 
failure, and t-.ermo is set to indicate the error. 
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NAME 

t—optmgmt - manage options for a transport endpoint 

SYNOPSIS 

#include <tiuser.h> 

int t_optmgmt(fd, req, ret) 
int fd; 

struct t—optmgmt ♦req; 
struct t_optmgmt *ret; 

DESCRIPTION 

The t^optmgmt function enables a transport user to retrieve, verify, or nego- 
tiate protocol options with the transport provider. Fd identifies a bound 
transport endpoint. 

The req and ret arguments point to a t—optmgmt structure containing the fol- 
lowing members: 

struct netbuf opt; 
long flags; 

The opt field identifies protocol options, and the flags field is used to specify 
the action to take with those options. 

The options are represented by a nethuf [see fwfro(3); also for len, buf, and 
maxlen] structure in a manner similar to the address in t—bind. Req is used 
to request a specific action of the provider and to send options to the pro- 
vider. Len specifies the number of bytes in the options, buf points to the 
options buffer, and maxlen has no meaning for the req argument. The trans- 
port provider may return options and flag values to the user through ret. 
For ret, maxlen specifies the maximum size of the options buffer and buf 
points to the buffer where the options are to be placed. On return, len 
specifies the number of bytes of options returned. lAaxlen has no meaning 
for the req argument, but must be set in the ret argument to specify the 
maximum number of bytes the options buffer can hold. The actual structure 
and content of the options is imposed by the transport provider. 
The flags field of req can specify one of the following actions: 

T_NEGOTIATE This action enables the user to negotiate the values of the 
options specified in req with the transport provider. The 
provider will evaluate the requested options and negotiate 
the values, returning the negotiated values through ret. 

T_CHECK This action enables the user to verify whether the options 

specified in req are supported by the transport provider. 
On return, the flags field of ret will have either T_SUCCESS 
or T_FAILURE set to indicate to the user whether the 
options are supported. These flags are only meaningful for 
the T_CHECK request. 
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T_DEFAULT This action enables a user to retrieve the default options 
supported by the transport provider into the opt field of ret. 
In req, the len field of opt must be zero, and the buf field 
may be NULL. 

If issued as part of the connectionless-mode service, t—optrngmt may block 
due to flow control constraints. The function will not complete until the 
transport provider has processed all previously sent data units. 

On failure, t^ermo may be set to one of the following: 



[TBADF] 

[TOUTSTATE] 
[TACCES] 

[TBADOPT] 

[TBADFLAG] 
[TBUFOVFLW] 



[TSYSERR] 



The specified file descriptor does not refer to a trans- 
port endpoint. 

The function was issued in the wrong sequence. 

The user does not have permission to negotiate the 
specified options. 

The specified protocol options were in an incorrect 
format or contained illegal information. 

An invalid flag was specified. 

The number of bytes allowed for an incoming argu- 
ment is not sufficient to store the value of that argu- 
ment. The information to be returned in ret will be 
discarded. 

A system error has occurred during execution of this 
function. 



SEE ALSO 

intro(3), t_getinfo(3N), t_open(3N). 

Programmer's Guide. 
DIAGNOSTICS 

The t-optmgmt function returns on success and -1 on failure, and t-£rrno 
is set to indicate the error. 
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NAME 

t_rcv - receive data or expedited data sent over a connection 

SYNOPSIS 

int t_rcv(fd, but nbytes, flags) 
int fd; 
char ♦buf; 
unsigned nbytes; 
int *flags; 

DESCRIPTION 

This function receives either normal or expedited data. Fd identifies the 
local transport endpoint through which data will arrive; buf points to a 
receive buffer where user data will be placed; and nbytes specifies the size of 
the receive buffer. Flags may be set on return from t—vcv and specifies 
optional flags as described below. 

By default, t—rcv operates in synchronous mode and will wait for data to 
arrive if none is currently available. However, if 0_NDELAY is set (via 
t^open or fcntl), t—tcv will execute in asynchronous mode and will fail if no 
data is available. (See TNODATA below.) 

On rehim from the call, if T_JvlORE is set in flags, this indicates that there is 
more data and the current transport service data unit (TSDU) or expedited 
transport service data unit (ETSDU) must be received in multiple t^rcv calls. 
Each t—rcv with the T_MORE flag set indicates that another t^rcv must fol- 
low immediately to get more data for the current TSDU. The end of the 
TSDU is identified by the return of a t-.rcv call with the T_MORE flag not 
set. If the transport provider does not support the concept of a TSDU as 
indicated in the info argument on return from t^open or t-getinfo, the 
T__MORE flag is not meaningful and should be ignored. 
On return, the data returned is expedited data if T_EXPEDITED is set in flags. 
If the number of bytes of expedited data exceeds nbytes, t-rcv will set 
T_EXPEDITED and T_MORE on return from the initial call. Subsequent calls 
to retrieve the remaining ETSDU will not have T_EXPEDITED set on return. 
The end of the ETSDU is identified by the return of a t^rcv call with the 
T_MORE flag not set. 

If expedited data arrives after part of a TSDU has been retrieved, receipt of 
the remainder of the TSDU will be suspended until the ETSDU has been pro- 
cessed. Only after the full ETSDU has been retrieved (T_MORE not set) will 
the remainder of the TSDU be available to the user. 
On failure, t^ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a trans- 

port endpoint. 

[TNODATA] 0_NDELAY was set, but no data is currently available 

from the transport provider. 

[TLOOK] An asynchronous event has occurred on this transport 

endpoint and requires immediate attention. 
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[TNOTSUPPORT] This function is not supported by the underlying trans- 
port provider. 

[TSYSERR] A system error has occurred during execution of this 

function. 

SEE ALSO 

t_>open(3N), t_snd(3N). 

Programmer's Guide. 

DIAGNOSTICS 

On successful completion, t—rcv returns the number of bytes received, and it 
returns -1 on failure, and t—errno is set to indicate the error. 
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NAME 

t-_rcvconnect - receive the confirmation from a connect request 

SYNOPSIS 

#include <tiuser.h> 

int t__rcvconnect(fd, call) 
int fd; 

struct t_call *call; 
DESCRIPTION 

This function enables a calling transport user to determine the status of a 
previously sent connect request and is used in conjunction with connect to 
establish a connection in asynchronous mode. The connection will be esta- 
blished on successful completion of this function. 

Fd identifies the local transport endpoint where communication will be esta- 
blished, and call contains information associated with the newly established 
connection. Call points to a t—call structure which contains the following 
members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro(3). In call, addr returns the protocol address 
associated with the responding transport endpoint, opt presents any 
protocol-specific information associated with the connection, udata points to 
optional user data that may be returned by the destination transport user 
during connection establishment, and sequence has no meaning for this 
function. 

The maxlen [see netbuf in intro{3)] field of each argument must be set before 
issuing this function to indicate the maximum size of the buffer for each. 
However, call may be NULL, in which case no information is given to the 
user on return from t^rcvconnect . By default, tscvconnect executes in syn- 
chronous mode and waits for the connection to be established before return- 
ing. On return, the addr, opt, and udata fields reflect values associated with 
the connection. 

If 0_NDELAY is set (via t^open or fcntl), t-rcvconnect executes in asynchro- 
nous mode and reduces to a poll for existing connect confirmations. If none 
are available, t-rcvconnect fails and returns immediately without waiting for 
the connection to be established. (See TNODATA below.) t-rcvconnect 
must be re-issued at a later time to complete the connection establishment 
phase and retrieve the information returned in call. 
On failure, t-.ermo may be set to one of the following: 
[TBADF] The specified file descriptor does not refer to a trans- 

port endpoint. 

[TBUFOVFLW] The number of bytes allocated for an incoming argu- 

ment is not sufficient to store the value of that argu- 
ment and the connect information to be returned in 
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call will be discarded. The provider's state, as seen 
by the user, will be changed to DATAXFER. 

0_NDELAY was set, but a connect confirmation has 
not yet arrived. 

An asynchronous event has occurred on this transport 
connection and requires immediate attention. 

This function is not supported by the underlying 
transport provider. 

A system error has occurred during execution of this 
function. 

SEE ALSO 

intro(3), t_accept(3N), t_bind(3N), t_connect(3N), t_listen(3N), 
t_open(3N). 

Programmer's Guide. 

DIAGNOSTICS 

t^rcvconnect returns on success and -1 on failure, and t^ermo is set to 
indicate the error. 



[TNODATA] 
[TLOOK] 

[TNOTSUPPORT] 
[TSYSERR] 
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NAME 



t_rcvdis - retrieve information from disconnect 



SYNOPSIS 



#include <tiuser.h> 



t— rcvdis(fd, discon) 
int fd; 

struct t_discon *discon; 



DESCRIPTION 



This function is used to identify the cause of a disconnect, and to retrieve 
any user data sent with the disconnect. Fd identifies the local transport 
endpoint where the connection existed, and discon points to a t^iscon 
structure containing the following members: 

struct netbuf udata; 
int reason; 
int sequence; 

Netbuf is described in intro{3). Reason specifies the reason for the discon- 
nect through a protocol-dependent reason code, udata identifies any user 
data that was sent with the disconnect, and sequence may identify an out- 
standing connect indication with which the disconnect is associated. 
Sequence is only meaningful when t—rcvdis is issued by a passive transport 
user who has executed one or more t^listen functions and is processing the 
resulting connect indications. If a disconnect indication occurs, sequence can 
be used to identify which of the outstanding connect indications is associ- 
ated with the disconnect. 

If a user does not care if there is incoming data and does not need to know 
the value of reason or sequence, discon may be NULL and any user data asso- 
ciated with the disconnect will be discarded. However, if a user has 
retrieved more than one outstanding connect indication (via t— listen) and 
discon is NULL, the user will be unable to identify with which connect indi- 
cation the disconnect is associated. 

On failure, t^errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a trans- 



port endpoint. 



[TNODIS] 



No disconnect indication currently exists on the speci- 
fied transport endpoint. 



[TBUFOVFLW] 



The number of bytes allocated for incoming data is 
not sufficient to store the data. The provider's state, 
as seen by the user, will change to T_IDLE, and the 
disconnect indication information to be returned in 
discon will be discarded. 



[TSYSERR] 



[TNOTSUPPORT] 



This function is not supported by the underlying 
transport provider. 

A system error has occurred during execution of this 
function. 
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SEE ALSO 

intro(3), t_connect(3N), t_listen(3N), t_open(3N), t_snddis(3N). 
Programmer's Guide. 
DIAGNOSTICS 

The t—TCvdis function returns on success and -1 on failure, and t^errno is 
set to indicate the error. 
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NAME 

t_rcvrel - acknowledge receipt of an orderly release indication 

SYNOPSIS 

#include <tiuser.h> 

t_rcvrel(fd) 
int fd; 

DESCRIPTION 

This function is used to acknowledge receipt of an orderly release indica- 
tion. Fd identifies the local transport endpoint where the connection exists. 
After receipt of this indication, the user may not attempt to receive more 
data because such an attempt will block forever. However, the user may 
continue to send data over the connection if t^ndrel has not been issued by 
the user. 

This function is an optional service of the transport provider, and is only 
supported if the transport provider returned service type T_COTS_ORD on 
t-.open or t—getinfo. 

On failure, t—ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a trans- 

port endpoint. 

[TNOREL] No orderly release indication currently exists on the 

specified transport endpoint. 

[TLOOK] An asynchronous event has occurred on this transport 

endpoint and requires immediate attention. 

[TNOTSUPPORT] This function is not supported by the underlying 
transport provider. 

[TSYSERR] A system error has occurred during execution of this 

function. 

SEE ALSO 

t_open(3N), t_sndrel(3N). 

Programmer's Guide. 

DIAGNOSTICS 

The t—rcvrel function returns on success and -1 on failure, and t—errno is 
set to indicate the error. 
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NAME 

t—rcvudata - receive a data unit 

SYNOPSIS 

#include <tiuser.h> 

int t^cvudata(fd, unitdata, flags) 
int fd; 

struct t—unitdata *unitdata; 
int '''flags; 

DESCRIPTION 

This function is used in connectionless mode to receive a data unit from 
another transport user. Fd identifies the local transport endpoint through 
which data will be received, unitdata holds information associated with the 
received data unit, and flags is set on return to indicate that the complete 
data unit was not received. Unitdata points to a t^unitdata structure con- 
taining the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 

The maxlen [see netbujm intro(3)] field of addr, opt, and udata must be set 
before issuing this function to indicate the maximum size of the buffer for 
each. 

On return from this call, addr specifies the protocol address of the sending 
user, opt identifies protocol-specific options that were associated with this 
data unit, and udata specifies the user data that was received. 

By default, tscvudata operates in synchronous mode and will wait for a 
data unit to arrive if none is currently available. However, if 0_NDELAY is 
set (via t^open or fcntl), t^rcvudata will execute in asynchronous mode and 
will fail if no data units are available. 

If the buffer defined in the udata field of unitdata is not large enough to 
hold the current data unit, the buffer will be filled and T_MORE will be set 
in flags on return to indicate that another t—rcvudata should be issued to 
retrieve the rest of the data unit. Subsequent t—rcvudata call(s) will return 
zero for the length of the address and options until the full data unit has 
been received. 

On failure, t—errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a trans- 

port endpoint. 

[TNODATA] 0_NDELAY was set, but no data units are currently 

available from the transport provider. 

[TBUFOVFLW] The number of bytes allocated for the incoming pro- 

tocol address or options is not sufficient to store the 
information. The unit data information to be returned 
in unitdata will be discarded. 
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[TLOOK] An asynchronous event has occurred on this transport 

endpoint and requires immediate attention. 

[TNOTSUPPORT] This function is not supported by the underlying 
transport provider. 

[TSYSERR] A system error has occurred during execution of this 

function. 

SEE ALSO 

intro(3), t_rcvuderr(3N), t_sndudata(3N). 
Programmer's Guide. 
DIAGNOSTICS 

The t—rcvudata function returns on successful completion and -1 on 
failure, and t—errno is set to indicate the error. 
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NAME 

t_rcvuderr - receive a unit data error indication 

SYNOPSIS 

#include <tiuser.h> 

int t_j*cvuderr(fd, uderr) 
int fd; 

struct t—uderr *uderr; 
DESCRIPTION 

This function is used in connectionless mode to receive information con- 
cerning an error on a previously sent data unit, and should only be issued 
following a unit data error indication. It informs the transport user that a 
data unit with a specific destination address and protocol options produced 
an error. Fd identifies the local transport endpoint through which the error 
report will be received, and uderr points to a t-juderr structure containing 
the following members: 

struct netbuf addr; 
struct netbuf opt; 
long error; 

Nethuf is described in intro(3). The maxlen [see netbuf in intro(3)] field of 
addr and opt must be set before issuing this function to indicate the max- 
imum size of the buffer for each. 

On return from this call, the addr structure specifies the destination protocol 
address of the erroneous data unit; the opt structure identifies protocol- 
specific options that were associated with the data unit; and error specifies a 
protocol-dependent error code. 

If the user does not care to identify the data unit that produced an error, 
uderr may be set to NULL and t^rcvuderr will simply clear the error indica- 
tion without reporting any information to the user. 

On failure, t—ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TNOUDERR] No unit data error indication currently exists on the 

specified transport endpoint. 

[TBUFOVFLW] The number of bytes allocated for the incoming protocol 

address or options is not sufficient to store the informa- 
tion. The unit data error information to be returned in 
uderr will be discarded. 

[TNOTSUPPORT] This function is not supported by the underlying trans- 
port provider. 

[TSYSERR] A system error has occurred during execution of this 

function. 
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SEE ALSO 

intro(3), t_j:cvudata(3N), t_sndudata(3N). 
Programmer's Guide, 
DIAGNOSTICS 

The t—rcvuderr function returns on successful completion and -1 on 
failure, and t^errno is set to indicate the error. 
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NAME 

t_snd - send data or expedited data over a connection 

SYNOPSIS 

#include <tiuser.h> 

int t— snd(fd, buf, nbytes, flags) 
int fd; 
char *buf; 
unsigned nbytes; 
int flags; 

DESCRIPTION 

This function is used to send either normal or expedited data, fd identifies 
the local transport endpoint over which data should be sent, huf points to 
the user data, nbytes specifies the number of bytes of user data to be sent, 
and flags specifies any optional flags described below. 

By default, t^nd operates in synchronous mode and may wait if flow con- 
trol restrictions prevent the data from being accepted by the local transport 
provider at the time the call is made. However, if 0_NDELAY is set (via 
t^open or fcntl), t^nd will execute in asynchronous mode, and will fail 
immediately if there are flow control restrictions. 

Even when there are no flow control restrictions, t^nd will wait if STREAMS 
internal resources are not available, regardless of the state of 0_NDELAY. 

On successful completion, t^nd returns the number of bytes accepted by 
the transport provider. Normally this will equal the number of bytes speci- 
fied in nbytes. However, if 0_-NDELAY is set, it is possible that only part of 
the data will be accepted by the transport provider. In this case, t^nd will 
set T_MORE for the data that was sent (see below) and will return a value 
less than nbytes. If nbytes is zero, no data will be passed to the provider 
and t—snd will return zero. 

If T_EXPED1TED is set in flags, the data will be sent as expedited data, and 
will be subject to the interpretations of the transport provider. 

If T_MORE is set in flags, or is set as described above, an indication is sent 
to the transport provider that the transport service data unit (TSDU) or 
expedited transport service data unit (ETSDU) is being sent through multiple 
t^nd calls. Each t^nd with the T-_MORE flag set indicates that another 
t^nd will follow v^th more data for the current TSDU. The end of the 
TSDU (or ETSDU) is identified by a t^nd call with the T_MORE flag not set. 
Use of T_MORE enables a user to break up large logical data units without 
losing the boundaries of those units at the other end of the connection. The 
flag implies i\othing about how the data is packaged for transfer below the 
transport interface. If the transport provider does not support the concept 
of a TSDU as indicated in the info argument on return from t^open or 
t^etinfo, the T_MORE flag is not meaningful and should be ignored. 

The size of each TSDU or ETSDU must not exceed the limits of the transport 
provider as returned by t—open or t—getinfo. If the size is exceeded, a 
TSYSERR with system error EPROTO will occur. However, the tsnd may 
not fail because EPROTO errors may not be reported immediately. In this 
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case, a subsequent call that accesses the transport endpoint will fail with the 
associated TSYSERR. 

If t^nd is issued from the T_IDLE state, the provider may silently discard 
the data. If t^nd is issued from any state other than T_DATAXFER, 
T_INREL or T_IDLE, the provider will generate a TSYSERR with system error 
EPROTO (which may be reported in the manner described above). 

On failure, t^ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a trans- 

port endpoint. 

[TFLOW] 0_NDELAY was set, but the flow control mechanism 

prevented the transport provider from accepting data 
at this time. 

[TNOTSUPPORT] This function is not supported by the underlying 
transport provider. 

[TSYSERR] A system error [see intro{2)] has been detected during 

execution of this function. 

SEE ALSO 

t-_open(3N), t_rcv(3N). 

Programmer's Guide. 

DIAGNOSTICS 

On successful completion, tsnd returns the number of bytes accepted by 
the transport provider, and it returns -1 on failure and t—ermo is set to indi- 
cate the error. 
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NAME 

t_snddis - send user-initiated disconnect request 

SYNOPSIS 

#include <tiuser.h> 

int t_snddis(fd, call) 
int fd; 

struct t_call *call; 
DESCRIPTION 

This function is used to initiate an abortive release on an already established 
connection or to reject a connect request. Fd identifies the local transport 
endpoint of the connection, and call specifies information associated with 
the abortive release. Call points to a t—call structure which contains the fol- 
lowing members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro{3). The values in call have different semantics, 
depending on the context of the call to t-^nddis. When rejecting a connect 
request, call must be non-NULL and contain a valid value of sequence to 
uniquely identify the rejected connect indication to the transport provider. 
The addr and opt fields of call are ignored. In all other cases, call need only 
be used when data is being sent with the disconnect request. The addr, opt, 
and sequence fields of the t^call structure are ignored. If the user does not 
wish to send data to the remote user, the value of call may be NULL. 

Udata specifies the user data to be sent to the remote user. The amount of 
user data must not exceed the limits supported by the transport provider as 
returned by t^open or t^getinfo. If the len field of udata is zero, no data 
will be sent to the remote user. 

On failure, t^ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a trans- 

port endpoint. 

[TOUTSTATE] The function was issued in the wrong sequence. The 

transport provider's outgoing queue may be flushed, so 
data may be lost. 

[TBADDATA] The amount of user data specified was not within the 

bounds allowed by the transport provider. The trans- 
port provider's outgoing queue will be flushed, so data 
may be lost. 

[TBADSEQ] An invalid sequence number was specified, or a NULL 

call structure was specified when rejecting a connect 
request. The transport provider's outgoing queue will 
be flushed, so data may be lost. 
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[TLOOK] An asynchronous event has occurred on this transport 

endpoint and requires immediate attention. 

[TNOTSUPPORT] This function is not supported by the underlying trans- 
port provider. 

[TSYSERR] A system error has occurred during execution of this 

function. 

SEE ALSO 

intro(3), t_connect(3N), t_getinfo(3N), t_listen(3N), t_open(3N). 
Programmer's Guide, 
DIAGNOSTICS 

The t-^nddis function returns on success and -1 on failure, and t—errno is 
set to indicate the error. 
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NAME 

t_sndrel - initiate an orderly release 

SYNOPSIS 

#include <tiuser.h> 

int t— sndrel(fd) 
int fd; 

DESCRIPTION 

This function is used to initiate an orderly release of a transport connection 
and indicates to the transport provider that the transport user has no more 
data to send. Fd identifies the local transport endpoint where the connec- 
tion exists. After issuing t^ndrel, the user may not send any more data 
over the connection. However, a user may continue to receive data if an 
orderly release indication has been received. 

This function is an optional service of the transport provider and is only 
supported if the transport provider returned service t)q?e T_COTS_ORD on 
t—open or t^getinfo. 

On failure, t^ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a trans- 

port endpoint. 

[TFLOW] 0_NDELAY was set, but the flow control mechanism 

prevented the transport provider from accepting the 
function at this time. 

[TNOTSUPPORT] This function is not supported by the underlying 
transport provider. 

[TSYSERR] A system error has occurred during execution of this 

function. 

SEE ALSO 

t_open(3N), t_rcvrel(3N). 

Programmer's Guide, 

DIAGNOSTICS 

The t^ndrel function returns on success and -1 on failure, and t—errno is 
set to indicate the error. 
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NAME 

t— sndudata - send a data unit 

SYNOPSIS 

#include <tiuser.h> 

int t_sndudata(fd, unitdata) 
int f d; 

struct t_unitdata *unitdata; 
DESCRIPTION 

This function is used in connectionless mode to send a data unit to another 
transport user. Fd identifies the local transport endpoint through which 
data will be sent, and unitdata points to a t— unitdata structure containing 
the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 

Netbuf is described in intro{3). In unitdata , addr specifies the protocol 
address of the destination user, opt identifies protocol-specific options that 
the user wants associated with this request, and udata specifies the user data 
to be sent. The user may choose not to specify what protocol options are 
associated with the transfer by setting the len field of opt to zero. In this 
case, the provider may use default options. 

If the len field of udata is zero, no data unit will be passed to the transport 
provider; t— sndudata will not send zero-length data units. 

By default, t^ndudata operates in synchronous mode and may wait if flow 
control restrictions prevent the data from being accepted by the local trans- 
port provider at the time the call is made. However, if 0_NDELAY is set 
(via t^open or fcntl), t^ndudata will execute in asynchronous mode and 
will fail under such conditions. 

If t— sndudata is issued from an invalid state, or if the amount of data speci- 
fied in udata exceeds the TSDU size as returned by t—open or t^getinfo, the 
provider will generate an EPROTO protocol error. (See TSYSERR below.) 

On failure, t^ermo may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TFLOW] 0_NDELAY was set, but the flow control mechanism 

prevented the transport provider from accepting data at 
this time. 

[TNOTSUPPORT] This function is not supported by the underlying trans- 
port provider. 

[TSYSERR] A system error has occurred during execution of this 

function. 

SEE ALSO 

intro(3), t_rcvudata(3N), t_rcvuderr(3N). 
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Programmers Guide. 
DIAGNOSTICS 

The t^ndudata function returns on successful completion and -1 on 
failure, and t—ermo is set to indicate the error. 
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NAME 

t_sync - synchronize transport library 

SYNOPSIS 

#include <tiuser.h> 

int t— sync(fd) 
int fd; 

DESCRIPTION 

For the transport endpoint specified by fd, tsync synchronizes the data 
structures managed by the transport library with information from the 
underlying transport provider. In doing so, it can convert a raw file descrip- 
tor [obtained via open{l), dup(2), or as a result of a fork{2) and exec(2)] to an 
initialized transport endpoint, assuming that file descriptor referenced a 
transport provider. This function also allows two cooperating processes to 
synchronize their interaction with a transport provider. 

For example, if a process forks a new process and issues an exec, the new 
process must issue a t^ync to build the private library data structure associ- 
ated with a transport endpoint and to synchronize the data structure with 
the relevant provider information. 

It is important to remember that the transport provider treats all users of a 
transport endpoint as a single user. If multiple processes are using the same 
endpoint, they should coordinate their activities so as not to violate the state 
of the provider, f—sync returns the current state of the provider to the user, 
thereby enabling the user to verify the state before taking further action. 
This coordination is only valid among cooperating processes; it is possible 
that a process or an incoming event could change the provider's state after a 
tsync is issued. 

If the provider is undergoing a state transition when tsync is called, the 
function will fail. 

On failure, tsrmo may be set to one of the following: 

[TBADF] The specified file descriptor is a valid open file descrip- 

tor but does not refer to a transport endpoint. 

[TSTATECHNG] The transport provider is undergoing a state change. 

[TSYSERR] A system error has occurred during execution of this 

function. 

SEE ALSO 

dup(2), exec(2), fork(2), open(2). 

Programmer's Guide. 

DIAGNOSTICS 

The tsync function returns the state of the transport provider on successful 
completion and -1 on failure, and tsrrno is set to indicate the error. The 
state returned may be one of the following: 

T_UNBND unbound 
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T_IDLE 

T_OUTCON 

T_INCON 

T_DATAXFER 

T_OUTREL 

T_INREL 



idle 

outgoing connection pending 
incoming connection pending 
data transfer 

outgoing orderly release (waiting for an orderly release 
indication) 

incoming orderly release (waiting for an orderly release 
request). 
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NAME 

t_unbind - disable a transport endpoint 

SYNOPSIS 

#include <tiuser.h> 

int L.unbind(fd) 
int fd; 

DESCRIPTION 

The t^unbind function disables the transport endpoint specified by fd, 
which was previously bound by tJbind (3N). On completion of this call, no 
further data or events destined for this transport endpoint will be accepted 
by the transport provider. 

On failure, t—errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TOUTSTATE] The function was issued in the wrong sequence. 

[TLOOK] An as5mchronous event has occurred on this transport end- 

point. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

t_bind(3N). 

Programmer's Guide. 

DIAGNOSTICS 

The t^unbind function returns on success and -1 on failure, and t—ermo is 
set to indicate the error. 
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NAME 

ungetc - push character back into input stream 

SYNOPSIS 

#include <stdio.h> 

int ungetc (c, stream) 
int c; 

FILE *stream; 
DESCRIPTION 

The ungetc function inserts the character c into the buffer associated with an 
input stream. That character, c, will be returned by the next getc{3S) call on 
that stream. The ungetc function returns c, and leaves the file stream 
unchanged. 

One character of pushback is guaranteed, provided something has already 
been read from the stream and the stream is actually buffered. 

If c equals EOF, ungetc does nothing to the buffer and returns EOF. 

The fseek{3S) function erases all memory of inserted characters. 

SEE ALSO 

fseek(3S), getc(3S), setbuf(3S), stdio(3S). 

DIAGNOSTICS 

ungetc returns EOF if it cannot insert the character. 

BUGS 

When stream is stdin, one character may be pushed back onto the buffer 
without a previous read statement. 
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NAME 

vprintf, vfprintf, vsprintf - print formatted output of a varargs argument list 

SYNOPSIS 

#include <stdio.h> 
#include <varargs.h> 

int vprintf (fonnat, ap) 
char ^format; 
va-Jist ap; 

int vfprintf (stream, format, ap) 
FILE '('Stream; 
char '('format; 
vaJist ap; 

int vsprintf (s, format, ap) 
char *s, ^format; 
va_list ap; 

DESCRIPTION 

The vprintf, vfprintf, and vsprintf functions are the same as printf, fprintf, 
and sprintf respectively, except that instead of being called with a variable 
number of arguments, they are called with an argument list as defined by 
varargs{5). 

EXAMPLE 

The following demonstrates the use of vfprintf to write an error routine. 

#include <stdio.h> 
#include <varargs.h> 

/♦ 

♦ error should be called like 

♦ error ( function_name , format, argi, arg2 . . . ) ; */ 
/*VARARGS*/ 

void 

error ( va_alist ) 

/♦ Note that the f unction_name and format arguments cannot be 

♦ separately declared because of the definition of varargs. */ 
va_dcl 

{ 

va_list args ; 
char *f mt ; 

va_start ( args ) ; 

/* print out name of function causing error */ 

( void ) f printf ( stderr , "ERROR in %s : ", va_arg(args, char *) ) ; 

fmt = va_arg(args, char *) ; 

/* print out remainder of message */ 

( void ) vfprintf ( stderr , fmt, args); 

va_end ( args ) ; 

( void ) abort ( ) ; 

} 
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SEE ALSO 

printf(3S), varargs(5). 
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NAME 

intro - introduction to file formats 
DESCRIPTION 

This section outlines the formats of various files. The C structure declara- 
tions for the file formats are given where applicable. Usually, the header 
files containing these structure declarations can be found in the directories 
/usr/include or /usr/include/sys. For inclusion in C language programs, 
hovy^ever, the syntax #include <filename.h> or #include 
<sys/£ilename.h> should be used. 
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NAME 

a.out - common assembler and link editor output 

SYNOPSIS 

#include <a.out.h> 

DESCRIPTION 

The file name a.out is the default output file name from the link editor 
ld{l). The link editor will make a.out executable if there were no errors in 
linking. The output file of the assembler as (1) also follows the common 
object file format of the a.out file although the default file name is different. 

A common object file consists of a file header, a UNIX system header (if the 
file is link editor output), a table of section headers, relocation information, 
(optional) line numbers, a symbol table, and a string table. The order is 
given below. 



File header. 

UNIX system header. 

Section 1 header. 

Section n header. 
Section 1 data. 

Section n data. 
Section 1 relocation. 

Section n relocation. 
Section 1 line numbers. 

Section n line numbers. 
Symbol table. 
String table. 



The last three parts of an object file (line numbers, symbol table and string 
table) may be missing if the program was linked with the -s option of ld{l) 
or if they were removed by strip{l). Also note that the relocation informa- 
tion will be absent after linking unless the -r option of ld(l) was used. The 
string table exists only if the symbol table contains symbols with names 
longer than eight characters. 

The sizes of each section (contained in the header, discussed below) are in 
bytes. 

When an a.out file is loaded into memory for execution, three logical seg- 
ments are set up: the text segment, the data segment (initialized data fol- 
lowed by uninitialized, the latter actually being initialized to all O's), and a 
stack. On your computer, the text segment starts at location virtual address 
0. 
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The a. out file produced by ld{l) may have one of two magic numbers in the 
first field of the UNIX system header. A magic number of 0410 indicates 
that the executable must be swapped through the private swapping store of 
the UNIX system, while the magic number 0413 causes the system to 
attempt to page the text directly from the a.out file. 

In a 0410 executable, the text section is loaded at virtual location 
0x00000000. The data section is loaded immediately following the end of 
the text section. 

For a 0413 executable, the headers (file header, UNIX system header, and 
section headers) are loaded at the beginning of the text segment and the text 
immediately follows the headers in the user address space. The first text 
address will equal the sum of the sizes of the headers, and will vary 
depending on the number of sections in the a.out file. In an a.out file with 
3 sections (.text, .data, and .bss) the first text address is at OxOOOOOODO. The 
data section starts in the next page table directory after the last one used by 
the text section, in the first page of that directory, with an offset into that 
page equal to the 1st unused memory offset in the last page of text. That is 
to say, given that etext is the address of the last byte of the text section, the 
1st byte of the data section will be at 0x00400000 + (etext & OxFFCOOOOO) + 
{(etext-\-l) & OxFFCOOFFF). 

On the 80386 computer the stack begins at location 7FFFFFFC and grows 
toward lower addresses. The stack is automatically extended as required. 
The data segment is extended only as requested by the brk{2) system call. 

For relocatable files the value of a word in the text or data portions that is 
not a reference to an undefined external symbol is exactly the value that 
will appear in memory when the file is executed. If a word in the text 
involves a reference to an undefined external symbol, there will be a reloca- 
tion entry for the word, the storage class of the symbol-table entry for the 
symbol will be marked as an "external symbol", and the value and section 
number of the symbol-table entry will be undefined. When the file is pro- 
cessed by the link editor and the external symbol becomes defined, the 
value of the s)anbol will be added to the word in the file. 

File Header 

The format of the filehdr header is 



struct filehdr 

{ 



}; 



unsigned short 
unsigned short 
long 
long 
long 

unsigned short 
unsigned short 



f_magic; /* magic number */ 

f_nscns; /* number of sections */ 

f_timdat; /* time and date stamp */ 

f__symptr; /* file ptr to symtab */ 

f_nsyms; /* # symtab entries */ 

f_opthdr; /* sizeof(opt hdr) */ 

f_Jlags; /* flags */ 
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UNIX System Header 

The format of the UNIX system header is 

typedef struct aouthdr 

{ 

short magic; 

short vstamp; 

long tsize; 

long dsize; 

long bsize; 

long entry; 

long text—Start; 

long data_start; 
} AOUTHDR; 

Section Header 

The format of the section header is 

struct scnhdr 

{ 

char 
long 
long 
long 
long 
long 
long 

unsigned 
unsigned 
^ long 

Relocation 

Object files have one relocation entry for each relocatable reference in the 
text or data. If relocation information is present, it will be in the following 
format: 

struct reloc 

{ 

long r_vaddr; /* (virtual) address of reference */ 

long r-_symndx; /* index into symbol table */ 

ushort r— type; /* relocation type */ 

}' 

The start of the relocation information is S—relptr from the section header. 
If there is no relocation information, S—velptr is 0. 

Symbol Table 

The format of each symbol in the symbol table is 



/* magic number */ 
/* version stamp */ 
/* text size in bytes, padded */ 
/* initialized data (.data) */ 
/* uninitialized data (.bss) */ 
/* entry point */ 

/* base of text used for this file */ 
/* base of data used for this file */ 



s_name[SYMNMLEN];/* section name */ 

s_paddr; /* physical address */ 

s_vaddr; /* virtual address */ 

s_size; /* section size */ 

s_scnptr; /* file ptr to raw data */ 

s_relptr; /* file ptr to relocation */ 

s_Jnnoptr; /* file ptr to line numbers */ 

short s_nreloc; /* # reloc entries */ 

short S-_nlnno; /* # line number entries */ 

s_flags; /* flags */ 
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#define SYMNMLEN 8 
#define FILNMLEN 14 
#define DIMNUM 4 



struct syment 

{ 

union 

{ 

char 
struct 

{ 

long 

long 
} _n_n; 
char 

}-n; 

long 
short 

unsigned short 

char 

char 

}; 

#define n_name 
#define n_zeroes 
#define n_offset 
#define n_nptr 



/* all ways to get a symbol name ' 
_n_name[SYMNMLEN]; /* name of symbol */ 

_n_zeroes; /* == OL if in string table */ 
_n_offset; /* location in string table */ 

*__n__nptr[2]; /* allows overlaying */ 

n_value; /* value of symbol */ 

n_scnum; /* section number */ 

n—type; /* type and derived type */ 

n—sclass; /* storage class */ 

n__numaux; /* number of aux entries */ 



_n._n_jiame 
^._n__n._n_zeroes 
_n._n_n._n_offset 
_n._-n_nptr[l] 



Some symbols require more information than a single entry; they are fol- 
lowed by auxiliary entries that are the same size as a symbol entry. The for- 
mat follows. 
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union auxent { 
struct { 

long x_tagndx; 
union { 

struct { 

unsigned short x_lnno; 
unsigned short x_size; 
} x_Jnsz; 
long x_fsize; 
} x__misc; 
union { 

struct { 

long x_lnnoptr; 

long x_endndx; 
} x_fcn; 
struct { 

unsigned short x_dimen[DIMNUM]; 

} x_ary; 
} x_fcnary; 

unsigned short x__tvndx; 
} x_sym; 

struct { 

char x_fname[FILNMLENl; 
} x_file; 

struct { 

long x_scnlen; 

unsigned short x_nreloc; 

unsigned short x_Jilinno; 
} x_scn; 

struct { 

long x_tvfill; 

unsigned short x_tvlen; 

unsigned short x_tvran[2]; 
} x_tv; 

}; 

Indexes of symbol table entries begin at zero. The start of the symbol table 
is f^ymptr (from the file header) bytes from the beginning of the file. If the 
symbol table is stripped, f^ymptr is 0. The string table (if one exists) 
begins at fsymptr + (f^nsyms * SYMESZ) bytes from the beginning of the 
file. 

SEE ALSO 

as(l), cc(l), ld(l), brk(2). filehdr(4), ldfcn(4), linenum(4), reloc(4), scnhdr(4), 
syms(4). 
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NAME 

acct - per-process accounting file format 

SYNOPSIS 

#include <sys/acct.h> 

DESCRIPTION 

Files produced as a result of calling acct (2) have records in the form defined 
by <sys / acct,h> , whose contents are: 

typedef ushort comp_t; /* "floating point" */ 

/♦ 13-bit fraction, 3-bit exponent */ 



struct acct 
{ 



char 


ac_f lag ; 


/* 


char 


ac_stat ; 


/* 


ushort 


ac_uicl ; 


/* 


ushort 


ac_gid ; 


/* 


dev_t 


ac_tty ; 


/♦ 


time_t 


ac_btime ; 


/* 


comp_t 


ac_utime ; 


/* 


comp_t 


ac_stime ; 


/♦ 


comp_t 


ac_etime ; 


/* 


comp_t 


ac_mem ; 


/* 


comp_t 


ac_io ; 


/* 


comp_t 


ac_rw ; 


/* 


char 


ac_comm[ 8 ] ; 


/♦ 



Accounting flag */ 
Exit status */ 
Accounting user ID */ 
Accounting group ID */ 
control typewriter */ 
Beginning time */ 

acctng user time in clock ticks ♦/ 
acctng system time in clock ticks ♦/ 
acctng elapsed time in clock ticks */ 
memory usage in clicks */ 
chars trnsfrd by read/write */ 
number of block reads/writes */ 
command name */ 



extern struct acct acctbuf; 

extern struct inode ♦acctp; /* inode of accounting file */ 

#def ine AFORK 01 /* has executed fork, but no exec */ 

#def ine asu 02 /* used super-user privileges »/ 

#def ine ACCTF 0300 /* record type: 00 = acct */ 

In ac^flag, the AFORK flag is turned on by each fork{l) and turned off by an 
exec (2), The ac—comm field is inherited from the parent process and is reset 
by any exec. Each time the system charges the process with a clock tick, it 
also adds to ac—mem the current process size, computed as follows: 

(data size) + (text size) / (number of in-core processes using text) 
The value of ac-.mem / (ac^time + ac^utime) can be viewed as an approxi- 
mation to the mean process size, as modified by text sharing. 
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The structure tacct, which resides with the source files of the accounting 
commands, represents the total accounting format used by the various 
accounting commands: 

/* 

* total accounting (for acct period), also for day 
*/ 

struct tacct { 

uid_t ta_uid; 
char ta_name[8]; 
float ta_cpu[2]; 
float ta_kcore[2]; 
float ta_con [ 2 ] ; 
float ta_du; 
long ta_pc; 
unsigned short ta_sc; 
unsigned short ta_dc ; 
unsigned short ta_fee 

}; 

SEE ALSO 

acct(2), exec(2), fork(2). 
acct(lM), acctcom(l) in the User's/System Administrator's Reference Manual 

BUGS 

The ac—mem value for a short-lived command gives little information about 
the actual size of the command, because ac-mem may be incremented while 
a different command (e.g., the shell) is being executed by the process. 



/* userid ♦/ 

/♦ login name */ 

/* cum. cpu time, p/np (mins) */ 
/* cum kcore-minutes , p/np ♦/ 
/♦ cum. connect time, p/np, mins */ 
/♦ cum. disk usage ♦/ 
/♦ count of processes */ 
/* count of login sessions */ 
/♦ count of disk samples */ 
; /* fee for special services */ 
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NAME 

ar - common archive file format 

SYNOPSIS 

#include <ar.h> 

DESCRIPTION 

The archive command ar{l) is used to combine several files into one. 
Archives are used mainly as libraries to be searched by the link editor ld(l). 

Each archive begins with the archive magic string. 

#define ARMAG " !<arch>\n" /* magic string */ 
#define SARMAG 8 /* length of magic string */ 

Each archive which contains common object files [see a,out{4:)] includes an 
archive symbol table. This symbol table is used by the link editor ld(l) to 
determine which archive members must be loaded during the link edit pro- 
cess. The archive symbol table (if it exists) is always the first file in the 
archive (but is never listed) and is automatically created and/or updated by 
ar. 

Following the archive magic string are the archive file members. Each file 
member is preceded by a file member header which is of the following for- 
mat: 

#define ARFMAG "^n" /* header trailer string */ 
struct ar_hdr /* file member header */ 



All information in the file member headers is in printable ASCII. The 
numeric information contained in the headers is stored as decimal numbers 
(except for ar^mode which is in octal). Thus, if the archive contains print- 
able files, the archive itself is printable. 

The ar^name field is blank-padded and slash (/) terminated. The ar^date 
field is the modification date of the file at the time of its insertion into the 
archive. Common format archives can be moved from system to system as 
long as the portable archive command ar(l) is used. Conversion tools such 
as convert{l) exist to aid in the transportation of non-common format 
archives to this format. 



char 
char 
char 
char 
char 
char 
char 



ar__name[16]; 

ar_-date[12]; 

ar__uid[6]; 

ar_-.gid[6]; 

ar_mode[8]; 

ar_-size[10]; 

ar_fmag[2]; 



/* terminated file member name */ 

/* file member date */ 

/* file member user identification */ 

/* file member group identification */ 

/* file member mode (octal) */ 

/* file member size */ 

/* header trailer string */ 
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Each archive file member begins on an even byte boundary; a newline is 
inserted between files if necessary. Nevertheless the size given reflects the 
actual size of the file exclusive of padding. 

Notice there is no provision for empty areas in an archive file. 
If the archive symbol table exists, the first file in the archive has a zero 
length name (i.e., ar-name[0] == ). The contents of this file are as fol- 
lows: 

• The number of symbols. Length: 4 bytes. 

The array of offsets into the archive file. Length: 4 bytes * "the 
number of s)anbols". 

The name string table. Length: ar^ize - (4 bytes * ("the number 
of symbols" + 1)). 

The number of symbols and the array of offsets are managed with sgetl and 
sputl. The string table contains exactly as many null-terminated strings as 
there are elements in the offsets array. Each offset from the array is associ- 
ated with the corresponding name from the string table (in order). The 
names in the string table are all the defined global symbols found in the 
common object files in the archive. Each offset is the location of the archive 
header for the associated symbol. 

SEE ALSO 

ar(l), ld(l), strip(l), sputl(3X), a.out(4). 
WARNINGS 

Strip{l) will remove all archive symbol entries from the header. The 
archive symbol entries must be restored via the ts option of the ar{l) com- 
mand before the archive can be used with the link editor ld{l). 
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NAME 

cftime - language specific strings 
DESCRIPTION 

The programmer can create one printable file per language. These files 
must be kept in a special directory /lib/cftime. If this directory does not 
exist, the programmer should create it. The contents of these files are: 

• abbreviated month names (in order) 

• month names (in order) 

• abbreviated weekday names (in order) 

• weekday names (in order) 

• default strings that specify formats for local time (%x) and 

local date (%X). 

• defauh format for cftime, if the argument for cftime is zero or null. 

• AM (ante meridian) string 

• PM (post meridian) string 

Each string is on a line by itself. All white space is significant. The order 
of the strings in the above list is the same order in which the strings appear 
in the file shown below. 

EXAMPLE 

/lib /cftime /usa_english 

Jan 
Feb 

January 
February 

Sun 
Mon 

Sunday 
Monday 

%H:%M:%S 

%m/%d/%y 

%a %b %d %T %Z %Y 

AM 

PM 

FILES 

/lib/cftime - directory that contains the language specific printable files 
(create it if it does not exist) 

SEE ALSO 

ctime(3C). 
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NAME 

checklist - list of file systems processed by fsck and ncheck 
DESCRIPTION 

checklist resides in directory /etc and contains a list of, at most, 15 special 
file names. Each special file name is contained on a separate line and 
corresponds to a file system. Each file system will then be automatically 
processed by the fsck{\M) command. 

FILES 

/etc/checklist 
SEE ALSO 

fsck(lM), ncheck(lM) in the User's/System Administrator's Reference Manual 
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NAME 

core - format of core image file 
DESCRIPTION 

The UNIX system writes out a core image of a terminated process when any 
of various errors occur. See signal{2) for the list of reasons; the most com- 
mon are memory violations, illegal instructions, bus errors, and user- 
generated quit signals. The core image is called core and is written in the 
process's working directory (provided it can be; normal access controls 
apply). A process with an effective user ID different from the real user ID 
will not produce a core image. 

The first section of the core image is a copy of the system's per-user data 
for the process, including the registers as they were at the time of the fault. 
The size of this section depends on the parameter USIZE, which is defined 
in <8ys/param.h>. The remainder represents the actual contents of the 
user's core area when the core image was written. If the text segment is 
read-only and shared, or separated from data space, it is not dumped. 
The format of the information in the first section is described by the user 
structure of the system, defined in <sys/user.h>. Not included in this file 
are the locations of the registers. These are outlined in <sys/reg.h>. 

SEE ALSO 

sdb(l), setuid(2), signal(2). 

crash(lM) in the User's /System Administrator's Reference Manual 
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NAME 

cpio - format of cpio archive 
DESCRIPTION 

The header structure, when the -c option of cpio(l) is not used, is: 
struct { 

short h__magic, 

h_dev; 
ushort h_ino, 

h_mode, 

h_uid, 

h_gid; 
short h^nlink, 

h_rdev, 

h_mtime[2], 

h_namesize, 

h_filesize[2]; 
char h-_jiame[h__namesize rounded to word!; 

} Hdr; 

When the -c option is used, the header information is described by: 

sscanf(Chdr, " %6o%6o%6o%6o%6o%6o%6o%6o%l llo%6o%l llo%s " , 

&Hdr.h_magic, &Hdr.h_dev, &Hdr.h_ino, &Hdr.h_mode, 
&Hdr.h_uid, &Hdr.h_gid, &Hdr.h_nlink, &Hdr.h_rdev, 
&Longtime, &Hdr.h__namesize,&Longfile,Hdr.h_name); 

Longtime and Longfile are equivalent to Hdr.h-tntime and Hdr.h-filesize, 
respectively. The contents of each file are recorded in an element of the 
array of varying length structures, archive, together with other items 
describing the file. Every instance of h-magic contains the constant 070707 
(octal). The items h-Aev through h^mtime have meanings explained in 
stat(l). The length of the null-terminated path name h-.name, including the 
null byte, is given by h—namesize. 

The last record of the archive always contains the name TRAILER!!!. Special 
files, directories, and the trailer are recorded with h—filesize equal to zero. 

SEE ALSO 

stat(2). 

cpio{l), find(l) in the User's/System Administrator's Reference Manual. 
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NAME 

dir - format of directories 

SYNOPSIS 

#include <sys/dir.h> 

DESCRIPTION 

A directory behaves exactly like an ordinary file, save that no user may 
write into a directory. The fact that a file is a directory is indicated by a bit 
in the flag word of its inode entry [see /s(4)]. The structure of a directory 
entry as given in the include file is: 

#ifndef DIRSIZ 
#define DIRSIZ 14 
#endif 

struct direct 

{ 

ushort d—ino; 

char d_name[DIRSIZ]; 

}; 

By convention, the first two entries in each directory are for . and ... The 
first is an entry for the directory itself. The second is for the parent direc- 
tory. The meaning of . . is modified for the root directory of the master file 
system; there is no parent, so . . has the same meaning as .. 

SEE ALSO 

fs(4). 

CAVEAT 

dir{4) may not be compatible with future UNIX systems. It is recommended 
that you use dirent{4). 
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NAME 

dirent - file-system-independent directory entry 

SYNOPSIS 

#include <sys/dirent.h> 
#include <sys/types.h> 

DESCRIPTION 

Different file system types may have different directory entries. The dirent 
structure defines a file-system-independent directory entry, which contains 
information common to directory entries in different file system types. A 
set of these structures is returned by the getdents{2) system call. 

The dirent structure is defined below, 
struct dirent { 



The d—ino is a number which is unique for each file in the file system. The 
field d^off is the offset of that directory entry in the actual file system direc- 
tory. The field d—name is the beginning of the character array giving the 
name of the directory entry. This name is null terminated and may have at 
most MAXNAMLEN characters. This results in file system independent 
directory entries being variable length entities. The value of d^reclen is the 
record length of this entry. This length is defined to be the number of bytes 
between the current entry and the next one, so that it will always result in 
the next entry being on a long boundary. 

FILES 

/usr/include/sys /dirent.h 

SEE ALSO 

getdents(2). 



long 
off_t 



d_ino; 
d_off; 
d_reclen; 
d-_name[l]; 



unsigned short 
char 



}; 



- 1 - 



FILEHDR(4) 



FILEHDR(4) 



NAME 



filehdr - file header for common object files 



SYNOPSIS 

#include <£ilehdr.h> 

DESCRIPTION 

Every common object file begins with a 20-byte header. The following C 
struct declaration is used: 



struct 

{ 



} 



filehdr 

unsigned short f_magic ; 
unsigned short f_nscns ; 
long f_timdat ; 

long f__symptr ; 

long f_nsyms ; 

unsigned short f_opthdr ; 
unsigned short f_flags ; 



/* magic number */ 
/* number of sections */ 
/* time & date stamp */ 
/* file ptr to symtab */ 
/* # symtab entries */ 
/* sizeof(opt hdr) */ 
/* flags */ 



F^ymptr is the byte offset into the file at which the symbol table can be 
found. Its value can be used as the offset in fseek{3S) to position an I/O 
stream to the symbol table. The UNIX system optional header is 28-bytes. 
The valid magic numbers are given below: 



#define I286SMAGIC 

#define I286LMAGIC 

#define I386MAGIC 
#define FBOMAGIC 
#define N3BMAGIC 
#define NTVMAGIC 



0512 /* 80286 computers — small model 

programs */ 
0522 /* 80286 computers — large model 

programs */ 
0514 /* 80386 computers */ 
0560 /* 3B2 and 3B15 computers */ 

0550 /* 3B20 computer */ 

0551 /* 3B20 computer */ 



#define VAXWRMAGIC 0570 /* VAX writable text segments */ 
#define VAXROMAGIC 0575 /* VAX read only sharable 

text segments */ 

The value in f—timdat is obtained from the time{l) system call. Flag bits 



currently defined are: 

#define F_RELFLG 0000001 

#define F_EXEC 0000002 

#define F_LNNO 0000004 

#define F__LSYMS 0000010 

#define F_MINMAL 0000020 

#define F_UPDATE 0000040 

#define F_SWABD 0000100 

#define F_AR16WR 0000200 

#define F_AR32WR 0000400 

#define F_AR32W 0001000 



/* relocation entries stripped */ 

/* file is executable */ 

/* line numbers stripped */ 

/* local symbols stripped */ 

/* minimal object file */ 

/* update file, ogen produced */ 

/* file is " pre-swabbed " */ 

/* 16-bit DEC host */ 

/* 32-bit DEC host */ 

/* non-DEC host */ 
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#define F.J'ATCH 0002000 /* "patch" list in opt hdr */ 
#define F_80186 010000 /* contains 80186 instructions */ 
#define F_80286 020000 /* contains 80286 instructions */ 
#define F_BM32ID 0160000 /* WE32000 family ID field */ 
#define F_BM32B 0020000 /* fUe contains WE 32100 code */ 
#define F_BM32MAU 0040000 /* file reqs MAU to execute */ 
#define F-.BM32RST 0010000 /* this object file contains restore 

work around [3B15/3B2 only] */ 



SEE ALSO 

time(2), fseek(3S), a.out(4). 
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NAME 

fs: file system - format of system volume 

SYNOPSIS 

#include <sys/filsys.h> 
#include <sys/types.h> 
#include <sys/param.h> 

DESCRIPTION 

Every file system storage volume has a common format for certain vital 
information. Every such volume is divided into a certain number of 512- 
byte long sectors. Sector is unused and is available to contain a bootstrap 
program or other information. 

Sector 1 is the superblock. The format of a super block is: 



struct filsys 






{ 

ushort 


s_isize; 


/* size in blocks of i-list */ 


daddr_t 


s_fsize; 


/* size in blocks of entire volume */ 


short 


s_nf r66 * 


/* number of addresses in s free * / 


daddr_t 


s_free[NICFREE]; 


/* free block list */ 


short 


s_ninode; 


/* number of inodes in s_inode */ 


ushort 


c inoHorMTPTMOnl* 
b inUUc[lN IV— IIN w U^f 


/* frpp irioHp li^t */ 

11 CC lllWl^C lis I ^/ 


char 


s__flock; 


/* lock during free list manipulation */ 


char 


s_ilock; 


/* lock during i-list manipulation */ 


char 


s_fmod; 


/* super block modified flag */ 


char 


s_ronly; 


/* mounted read-only flag */ 


time_t 


s_time; 


/* last super block update */ 


short 


s_dinfo[4]; 


/* device information */ 


daddr_t 


s_tfree; 


/* total free blocks*/ 


ushort 


s_tinode; 


/* total free inodes */ 


char 


s_fname[6]; 


/* file system name */ 


char 


s_fpack[6]; 


/* file system pack name */ 


long 


s_fill[12]; 


/* ADJUST to make size of filsys 




be 512; for 80286, array is s_fill[14] */ 


long 


s_state; 


/* file system state */ 


long 


s_magic; 


/* magic number to denote new 






file system */ 


long 

}; 


s_type; 


/* type of new file system */ 


#define FsMAGIC 


0xfdl87e20 


/* s_magic number */ 


#define Fslb 


1 


/* 512-byte block */ 


#define Fs2b 


2 


/* 1024-byte block */ 


#define FsOKAY 


0x7c269d38 


/* s_state: clean */ 


#define FsACTIVE 


0x5e72d81a 


/* s_state: active */ 


#define FsBAD 


0xcb096f43 


/* s_state: bad root */ 


#define FsBADBLK 


0xbadbcl4b 


/* s_state: bad block corrupted it */ 
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S—type indicates the file system type. Currently, two types of file systems 
are supported: the original 512-byte logical block and the improved 1024- 
byte logical block. S^agic is used to distinguish the original 512-byte 
oriented file systems from the newer file systems. If this field is not equal 
to the magic number, fshMGIC, the type is assumed to be fslb, otherwise the 
s^type field is used. In the following description, a block is then deter- 
mined by the type. For the original 512-byte oriented file system, a block is 
512-bytes. For the 1024-byte oriented file system, a block is 1024-bytes or 
two sectors. The operating system takes care of all conversions from logical 
block numbers to physical sector numbers. 

Sstate indicates the state of the file system. A cleanly unmounted, not 
damaged file system is indicated by the FsOKAY state. After a file system 
has been mounted for update, the state changes to FsACTIVE. A special 
case is used for the root file system. If the root file system appears dam- 
aged at boot time, it is mounted but marked FsBAD. Lastly, after a file sys- 
tem has been unmounted, the state reverts to FsOKAY. 

S-isize is the address of the first data block after the i-list; the i-list starts 
just after the super block, namely in block 2; thus the i-list is S-Asize-1 
blocks long. S-fsize is the first block not potentially available for allocation 
to a file. These numbers are used by the system to check for bad block 
numbers; if an "impossible" block number is allocated from the free list or 
is freed, a diagnostic is written on the on-line console. Moreover, the free 
array is cleared, so as to prevent further allocation from a presumably cor- 
rupted free list. 

The free list for each volume is maintained as follows. The s^free array 
contains, in S-.free[\l • • v S-.free[s^nfree-ll to 49 numbers of free blocks. 
S^free[0] is the block number of the head of a chain of blocks constituting 
the free list. The first long in each free-chain block is the number (up to 50) 
of free-block numbers listed in the next 50 longs of this chain member. The 
first of these 50 blocks is the link to the next member of the chain. To allo- 
cate a block: decrement s^nfree, and the new block is s^free[s^nfree]. If 
the new block number is 0, there are no blocks left, so give an error. If 
s^nfree became 0, read in the block named by the new block number, 
replace S-tifree by its first word, and copy the block numbers in the next 5o' 
longs into the S-free array. To free a block, check if s^nfree is 50; if so, 
copy s^nfree and the s^free array into it, write it out, and set S-nfree to 0. 
In any event, set s^free[s-nfree] to the freed block's number and increment 
S—nfree. 

S—tfree is the total free blocks available in the file system. 

S^ninode is the number of free i-numbers in the s^inode array. To allocate 
an inode: if S—tiinode is greater than 0, decrement it and return 
s^inode[s^ninode]. If it was 0, read the i-list and place the numbers of all 
free inodes (up to 100) into the S-inode array, then try again. To free an 
inode, provided S-ninode is less than 100, place its number into 
s^inode[s^ninode] and increment s—ninode. If S—tiinode is already 100, do 
not bother to enter the freed inode into any table. This list of inodes is only 
to speed up the allocation process; the information as to whether the inode 
is really free or not is maintained in the inode itself. 
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S—tinode is the total free modes available in the file system. 

S— flock and s^ilock are flags maintained in the core copy of the file system 
while it is mounted and their values on disk are immaterial. The value of 
s—fmod on disk is likewise immaterial; it is used as a flag to indicate that the 
super block has changed and should be copied to the disk during the next 
periodic update of file system information. 
S—Tonly is a read-only flag to indicate write-protection. 

S-time is the last time the super block of the file system was changed, and 
is the number of seconds that have elapsed since 00:00 Jan. 1, 1970 (GMT). 
During a reboot, the s^time of the super block for the root file system is 
used to set the system's idea of the time. 

S—fname is the name of the file system and S—fpack is the name of the pack. 
I-numbers begin at 1, and the storage for inodes begins in block 2. Also, 
inodes are 64 bytes long. Inode 1 is reserved for future use. Inode 2 is 
reserved for the root directory of the file system, but no other i-number has 
a built-in meaning. Each inode represents one file. For the format of an 
inode and its flags, see inode (4). 

SEE ALSO 

mount(2), inode(4). 

fsck(lM), fsdb(lM), mkfs(lM) in the User's/System Administrator's Reference 
Manual. 
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NAME 

fspec - format specification in text files 
DESCRIPTION 

It is sometimes convenient to maintain text files on the UNIX system with 
non-standard tabs, (i.e., tabs which are not set at every eighth column). 
Such files must generally be converted to a standard format, frequentiy by 
replacing all tabs with the appropriate number of spaces, before they can be 
processed by UNIX system commands. A format specification occurring in 
the first line of a text file specifies how tabs are to be expanded in the 
remainder of the file. 

A format specification consists of a sequence of parameters separated by 
blanks and surrounded by the brackets <: and :>. Each parameter consists 
of a keyletter, possibly followed immediately by a value. The following 
parameters are recognized: 

itabs The t parameter specifies the tab settings for the file. The value 
of tabs must be one of the following: 

1. a list of column numbers separated by commas, indicating 
tabs set at the specified columns; 

2. a - followed immediately by an integer n, indicating tabs 
at intervals of n columns; 

3. a - followed by the name of a "canned" tab specification. 

Standard tabs are specified by t-8, or equivalentiy, tl,9,17,25, 
etc. The canned tabs which are recognized are defined by the 
tabs{l) command. 

The s parameter specifies a maximum line size. The value of 
size must be an integer. Size checking is performed after tabs 
have been expanded, but before the margin is prepended. 

The m parameter specifies a number of spaces to be prepended 
to each line. The value of margin must be an integer. 

The d parameter takes no value. Its presence indicates that the 
line containing the format specification is to be deleted from the 
converted file. 

e The e parameter takes no value. Its presence indicates that the 

current format is to prevail only until another format specifica- 
tion is encountered in the file. 

Default values, which are assumed for parameters not supplied, are t-8 and 
mO. If the s parameter is not specified, no size checking is performed. If 
the first line of a file does not contain a format specification, the above 
defaults are assumed for the entire file. The following is an example of a 
line containing a format specification: 

* <:t5,10,15 s72:> * 



ssize 

mmargin 
d 
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If a format specification can be disguised as a comment, it is not necessary 
to code the d parameter. 

SEE ALSO 

ed(l), newform(l), tabs(l) in the User's/System Administrator's Reference 
Manual. 
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NAME 

fstab - file-system-table 
DESCRIPTION 

The /etc/fstab file contains information about file systems for use by 
mount (IM) and mountalKlM). Each entry in /etc/fstab has the following 
format: 



FILES 



column 1 block special file name of file system or advertised 
remote resource 

column 2 mount-point directory 

column 3 "-r" if to be mounted read-only; "-d[r]" if remote 

column 4 (optional) file system type string 

column 5+ ignored 

White-space separates columns. Lines beginning with "# " are comments. 
Empty lines are ignored. 

A file-system-table might read: 

/dev/dsk/cld0s2 /usr S51K 
/dev/dsk/cldls2 /usr/src -r 
adv_jresource /mnt -d 



/etc/fstab 
SEE ALSO 

mount(lM), mountall(lM), rmountall(lM) in the User's/System 
Administrator's Reference Manual. 



- 1 - 



GETTYDEFS(4) 



GETTYDEFS(4) 



NAME 

gettydefs - speed and terminal settings used by getty 
DESCRIPTION 

The /etc/gettydefs file contains information used by getty (IM) to set up the 
speed and terminal settings for a line. It supplies information on what the 
login (1) prompt should look like. It also supplies the speed to try next if the 
user indicates the current speed is not correct by typing a <break> character. 

NOTE: Customers who need to support terminals that pass 8 bits to the 
system (as is t)q>ical outside the U.S.A.) must modify the entries in 
/etc/gettydefs as described in the WARNINGS section. 

Each entry in /etc/gettydefs has the following format: 

label# initial-flags # final-flags # login-prompt #next-label 

Each entry is followed by a blank line. The various fields can contain 
quoted characters of the form \b, \n, \c, etc., as well as \ nnn, where nnn is 
the octal value of the desired character. The various fields are: 

label This is the string against which getty (IM) tries to match its 

second argument. It is often the speed, such as 1200, at 
which the terminal is supposed to run, but it need not be 
(see below). 

initial-flags These flags are the initial ioctl(2) settings to which the termi- 
nal is to be set if a terminal type is not specified to 
getty(lM). The flags that getty(lM) understands are the 
same as the ones listed in /usr/include/sys/termio.h [see 
termio{7)]. Normally only the speed flag is required in the 
initial-flags, getty (IM) automatically sets the terminal to raw 
input mode and takes care of most of the other flags. The 
initial-flag settings remain in effect until getty (IM) executes 
login{l). 

final-flags These flags take the same values as the initial-flags and are 
set just before getty(lM) executes login{l). The speed flag is 
again required. The composite flag SANE takes care of most 
of the other flags that need to be set so that the processor 
and terminal are communicating in a rational fashion. The 
other two commonly specified final-flags are TAB3, so that 
tabs are sent to the terminal as spaces, and HUPCL, so that 
the line is hung up on the final close. 

login-prompt This entire field is printed as the login-prompt. Unlike the 
above fields where white space is ignored (a space, tab or 
new-line), they are included in the login-prompt field. 
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next-label If this entry does not specify the desired speed, indicated by 
the user typing a <break> character, then getty(lM) will 
search for the entry with next-label as its label field and set 
up the terminal for those settings. Usually, a series of 
speeds are linked together in this fashion, into a closed set; 
for instance, 2400 linked to 1200, which in turn is linked to 
300, which finally is linked to 2400. 

If getty{lM) is called without a second argument, then the first entry of 
/etc/gettydefs is used, thus making the first entry of /etc/gettydefs the 
default entry. It is also used if getty (IM) cannot find the specified label. If 
/etc/gettydefs itself is missing, there is one entry built into getty {IM) 
which will bring up a terminal at 300 baud. 

It is strongly recommended that after making or modifying /etc/gettydefs, 
it be run through getty(lM) with the check option to be sure there are no 
errors. 

FILES 

/etc/gettydefs 

SEE ALSO 

ioctl(2). 

getty(lM), login(l), stty(l), termio(7) in the User's/System Administrator's 
Reference Manual. 

WARNINGS 

To support terminals that pass 8 bits to the system (also, see the BUGS sec- 
tion), modify the entries in the /etc/gettydefs file for those terminals as fol- 
lows: add CSS to initial-flags and replace all occurrences of SANE with the 
values: BRKINT IGNPAR ICRNL IXON OPOST ONCLR CSS ISIG ICANON 
ECHO ECHOK 

An example of changing an entry in /etc/gettydefs is illustrated below. All 
the information for an entry must be on one line in the file. 

Original entry: 

CONSOLE # B9600 HUPCL OPOST ONLCR # B9600 
SANE IXANY TAB3 HUPCL # Console Login: # 
console 

Modified entry: 

CONSOLE # B9600 CSS HUPCL OPOST ONLCR # B9600 
BRKINT IGNPAR ICNRL IXON OPOST ONLCR CSS ISIG 
ICANON ECHO ECHOK IXANY TAB3 HUPCL # Console 
Login: # console 

This change will permit terminals to pass 8 bits to the system so long as the 
system is in MULTI-USER state. When the system changes to SINGLE-USER 
state, the getty{lM) is killed and the terminal attributes are lost. So to per- 
mit a terminal to pass 8 bits to the system in SINGLE-USER state, after you 
are in SINGLE-USER state, type [see stiy{l)]: 
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stty — istrip cs8 

BUGS 

8-bit with parity mode is not supported. 
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NAME 

gps - graphical primitive string, format of graphical files 
DESCRIPTION 

GPS is a format used to store graphical data. Several routines have been 
developed to edit and display GPS files on various devices. Also, higher 
level graphics programs such as plot [in stat{lG)] and vtoc [in toc{lG)] pro- 
duce GPS format output files. 

A GPS is composed of five types of graphical data or primitives. 
GPS PRIMITIVES 

lines The lines primitive has a variable number of points from which 
zero or more connected line segments are produced. The first 
point given produces a move to that location. (A move is a relo- 
cation of the graphic cursor without drawing.) Successive points 
produce line segments from the previous point. Parameters are 
available to set color, weight, and style (see below). 

arc The arc primitive has a variable number of points to which a 

curve is fit. The first point produces a move to that point. If 
only two points are included, a line connecting the points will 
result; if three points a circular arc through the points is drawn; 
and if more than three, lines connect the points. (In the future, a 
spline will be fit to the points if they number greater than three.) 
Parameters are available to set color, weight, and style. 

text The text primitive draws characters. It requires a single point 

which locates the center of the first character to be drawn. 
Parameters are color, font, textsize, and textangle. 

hardware The hardware primitive draws hardware characters or gives con- 
trol commands to a hardware device. A single point locates the 
beginning location of the hardware string. 

comment A comment is an integer string that is included in a GPS file but 
causes nothing to be displayed. All GPS files begin v^th a com- 
ment of zero length. 

GPS PARAMETERS 

color Color is an integer value set for arc, lines, and text primitives. 

weight Weight is an integer value set for arc and lines primitives to indi- 
cate line thickness. The value is narrow weight, 1 is bold, and 
2 is medium weight. 

style Style is an integer value set for lines and arc primitives to give 
one of the five different line styles that can be drawn on TEK- 
TRONIX 4010 series storage tubes. They are: 

solid 

1 dotted 

2 dot dashed 

3 dashed 

4 long dashed 
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font An integer value set for text primitives to designate the text font 
to be used in drawing a character string. (Currently font is 
expressed as a four-bit weight value followed by a four-bit style 
value.) 

textsize Textsize is an integer value used in text primitives to express the 
size of the characters to be drawn. Textsize represents the height 
of characters in absolute universe-units and is stored at one-fifth 
this value in the size-orientation (so) word (see below). 

textangle Textangle is a signed integer value used in text primitives to 
express rotation of the character string around the beginning 
point. Textangle is expressed in degrees from the positive x-axis 
and can be a positive or negative value. It is stored in the size- 
orientation (so) word as a value 256/360 of it's absolute value. 

ORGANIZATION 

GPS primitives are organized internally as follows: 

lines cw points sw 

arc cw points sw 

text cw point sw so [string] 

hardware cw point [string] 

comment cw [string] 

cw Cw is the control word and begins all primitives. It consists of 

four bits that contain a primitive-type code and twelve bits that 
contain the word-count for that primitive. 

point(s) Point{s) is one or more pairs of integer coordinates. Text and 
hardware primitives only require a single point. Point{s) are 
values within a Cartesian plane or universe having 64K (-32K to 
+32K) points on each axis. 

sw Sw is the style-word and is used in lines, arc, and text primitives. 

For all three, eight bits contain color information. In arc and 
lines eight bits are divided as four bits weight and four bits style. 
In the text primitive eight bits of sw contain the font. 

so So is the size-orientation word used in text primitives. Eight bits 

contain text size and eight bits contain text rotation. 

string String is a null-terminated character string. If the string does not 
end on a word boundary, an additional null is added to the GPS 
file to insure word-boundary alignment. 

SEE ALSO 

graphics(lG), stat(lG), toc(lG) in the User's /System Administrator's Reference 
Manual. 
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NAME 

group - group file 

DESCRIPTION 

group contains for each group the following information: 

group name 
encrypted password 
numerical group ID 

comma-separated list of all users allowed in the group 

This is an ASCII file. The fields are separated by colons; each group is 
separated from the next by a new-line. If the password field is null, no 
password is demanded. 

This file resides in directory /etc. Because of the encrypted passwords, it 
can and does have general read permission and can be used, for example, to 
map numerical group ID's to names. 

FILES 

/etc/group 

SEE ALSO 

newgrp(lM), passwd(4). 

passwd(l) in the Usefs/System Administrators Reference Manual 
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NAME 

inittab - script for the init process 
DESCRIPTION 

The inittab file supplies the script to init's role as a general process 
dispatcher. The process that constitutes the majority of init's process 
dispatching activities is the line process /etc/getty that initiates individual 
terminal lines. Other processes typically dispatched by init are daemons 
and the shell. 

The inittab file is composed of entries that are position-dependent and have 
the following format: 

id:rstate:action:process 

Each entry is delimited by a new-line; however, a backslash (\) preceding a 
new-line indicates a continuation of the entry. Up to 512 characters per 
entry are permitted. Comments may be inserted in the process field using 
the sh{l) convention for comments. Comments for lines that spawn gettys 
are displayed by the who{l) command. It is expected that they will contain 
some information about the line such as the location. There are no limits 
(other than maximum entry size) imposed on the number of entries within 
the inittab file. The entry fields are: 

id This is up to four characters used to uniquely identify an entry. 

rstate This defines the run-level in which this entry is to be processed. 

Run-levels effectively correspond to a configuration of processes in 
the system. That is, each process spawned by init is assigned a 
run-level or run-levels in which it is allowed to exist. The run- 
levels are represented by a number ranging from through 6. As 
an example, if the system is in run-level 1, only those entries hav- 
ing a 1 in the rstate field will be processed. When init is requested 
to change run-levels, all processes which do not have an entry in 
the rstate field for the target run-level will be sent the warning sig- 
nal (SIGTERM) and allowed a 20-second grace period before being 
forcibly terminated by a kill signal (SIGKILL). The rstate field can 
define multiple run-levels for a process by selecting more than one 
run-level in any combination from 0-6. If no run-level is specified, 
then the process is assumed to be valid at all run-levels 0-6. There 
are three other values, a, b, and c, which can appear in the rstate 
field, even though they are not true run-levels. Entries which 
have these characters in the rstate field are processed only when 
the telinit [see /nff(lM)] process requests them to be run (regard- 
less of the current run-level of the system). They differ from run- 
levels in that init can never enter run-level a, b, or c. Also, a 
request for the execution of any of these processes does not 
change the current run-level . Furthermore, a process started by an 
a, b, or c command is not killed when init changes levels. They 
are only killed if their line in /etc/inittab is marked off in the 
action field, their line is deleted entirely from /etc/inittab, or init 
goes into the SINGLE USER state. 
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action Key words in this field tell init how to treat the process specified 
in the process field. The actions recognized by init are as follows: 

respawn If the process does not exist, then start the process, 
do not wait for its termination (continue scanning the 
inittab file); and when it dies, restart the process. If 
the process currently exists, then do nothing and con- 
tinue scanning the inittab file. 

wait Upon init's entering the run-level that matches the 

entry's rstate, start the process and wait for its termi- 
nation. All subsequent reads of the inittab file while 
init is in the same run-level will cause init to ignore 
this entry. 

once Upon init's entering a run-level that matches the 

entry's rstate, start the process, do not wait for its ter- 
mination. When it dies, do not restart the process. If 
upon entering a new run-level, where the process is 
still running from a previous run-level change, the 
program will not be restarted. 

boot The entry is to be processed only at init's boot- time 

read of the inittab file. Init is to start the process, not 
wait for its termination; and when it dies, not restart 
the process. In order for this instruction to be mean- 
ingful, the rstate should be the default or it must 
match init's run-level at boot time. This action is 
useful for an initialization function following a 
hardware reboot of the system. 

bootwait The entry is to be processed the first time init goes 
from single-user to multi-user state after the system 
is booted. (If initdefault is set to 2, the process will 
run right after the boot.) Init starts the process, waits 
for its termination and, when it dies, does not restart 
the process. 

powerfail Execute the process associated with this entry only 
when init receives a power fail signal [SIGPWR see 
signal{2)]. 

powerwait Execute the process associated with this entry only 
when init receives a power fail signal (SIGPWR) and 
wait until it terminates before continuing any pro- 
cessing of inittab, 

off If the process associated with this entry is currently 

running, send the warning signal (SIGTERM) and 
wait 20 seconds before forcibly terminating the pro- 
cess via the kill signal (SIGKILL). If the process is 
nonexistent, ignore the entry. 

ondemand This instruction is really a synonym for the respawn 
action. It is functionally identical to respawn but is 
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given a different keyword in order to divorce its 
association with run4evels. This is used only with 
the a, b, or c values described in the rstate field. 

initdefault An entry with this action is only scanned when init 
initially invoked. Init uses this entry, if it exists, to 
determine which run-level to enter initially. It does 
this by taking the highest run-level specified in the 
rstate field and using that as its initial state. If the 
rstate field is empty, this is interpreted as 0123456 
and so init will enter run-level 6. Additionally, if init 
does not find an initdefault entry in /etc/inittab, 
then it will request an initial run-level from the user 
at reboot time. 

sysinit Entries of this type are executed before init tries to 
access the console (i.e., before the Console Login: 
prompt). It is expected that this entry will be used 
only to initialize devices on which init might try to 
ask the run-level question. These entries are exe- 
cuted and waited for before continuing. 

process This is a sh command to be executed. The entire process field is 
prefixed with exec and passed to a forked sh as sh -c 'exec com- 
mand'. For this reason, any legal sh syntax can appear in the pro- 
cess field. Comments can be inserted with the ; ^comment syntax. 

FILES 

/etc/inittab 

SEE ALSO 

exec(2), open(2), signal(2). 

getty(lM), init(lM), sh(l), sulogin(lM), who(l) in the User's/System 
Administrator's Reference Manual. 
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NAME 

inode - format of an inode 

SYNOPSIS 

#include <sys/types.h> 
#include <sys/ino.h> 

DESCRIPTION 

An inode for a plain file or directory in a file system has the following 
structure defined by <sys/ino.h>. 

/* Inode structure as it appears on a disk block. */ 
struct dinode 

{ 

ushort di-_mode; /* mode and type of file */ 

short di_nlink; /* number of links to file */ 

ushort di_uid; /* owner's user id */ 

ushort di__gid; /* owner's group id */ 

off_t di^ize; /* number of bytes in file */ 

char di-_addr[40]; /* disk block addresses */ 

time_t di_atime; /* time last accessed */ 

time_t di__mtime; /* time last modified */ 

time_t di_ctime; /* time of last file status change */ 

/* 

* the 40 address bytes: 

* 39 used; 13 addresses 

* of 3 bytes each. 

V 

For the meaning of the defined types off—t and time^t see types{5). 

SEE ALSO 

stat(2), fs(4), types(5). 
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NAME 

issue - issue identification file 
DESCRIPTION 

The file /etc/issue contains the issue or project identification to be printed 
as a login prompt. This is an ASCII file which is read by program getty and 
then written to any terminal spawned or respawned from the lines file. 

FILES 

/etc/issue 
SEE ALSO 

login(l) in the User's/System Administrator's Reference Manual. 
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NAME 

Idfcn - common object file access routines 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

DESCRIPTION 

The common object file access routines are a collection of functions for 
reading common object files and archives containing common object files. 
Although the calling program must know the detailed structure of the parts 
of the object file that it processes, the routines effectively insulate the calling 
program from knowledge of the overall structure of the object file. 

The interface between the calling program and the object file access routines 
is based on the defined t5^e LDFILE, defined as struct Idfile, declared in 
the header file ldfcn.h. The primary purpose of this structure is to provide 
uniform access to both simple object files and to object files that are 
members of an archive file. 

The function ldopen{3X) allocates and initializes the LDFILE structure and 
returns a pointer to the structure to the calling program. The fields of the 
LDFILE structure may be accessed individually through macros defined in 
Idfcn.h and contain the following information: 

LDFILE *ldptr; 

TYPE(ldptr) The file magic number used to distinguish between archive 
members and simple object files. 

lOPTR(ldptr) The file pointer returned by fopen and used by the standard 
input/output functions. 

OFFSET(ldptr) The file address of the beginning of the object file; the 
offset is non-zero if the object file is a member of an 
archive file. 

HEADER(ldptr) The file header structure of the object file. 

The object file access functions themselves may be divided into four 
categories: 

(1) functions that open or close an object file 

ldopen{3X) and ldaopen[see ldopen{3X)] 

open a common object file 
ldclose{3X) and ldaclose[see ldclose{3X)] 

close a common object file 

(2) functions that read header or symbol table information 

ldahread(3X) 
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read the archive header of a member of an archive 
file 

ldfhread(3X) 

read the file header of a common object file 
ldshread{3X) and ldnshread[see ldshread{3X)] 

read a section header of a common object file 
ldtbread{3X) 

read a symbol table entry of a common object file 
ldgetname{3X) 

retrieve a symbol name from a symbol table entry 
or from the string table 

(3) functions that position an object file at (seek to) the start of the 
section, relocation, or line number information for a particular sec- 
tion. 

ldohseek(3X) 

seek to the optional file header of a common object 
file 

ldsseek{3X) and ldnsseek[see ldsseek(3X)] 

seek to a section of a common object file 

ldrseek{3X) and ldnrseek[see ldrseek{3X)] 

seek to the relocation information for a section of a 
common object file 

ldlseek(3X) and ldnlseek[see ldlseek{3X)] 

seek to the line number information for a section of 
a common object file 

ldthseek(3X) 

seek to the symbol table of a common object file 

(4) the function ldtbindex(3X) which returns the index of a particular 
common object file symbol table entry. 

These functions are described in detail on their respective manual pages. 

All the functions except ldopen{3X\ ldgetname{3X), ldthindex{3X) return 
either SUCCESS or FAILURE, both constants defined in ldfcn.h. Ldopen{3X) 
and ldaopen[{see ldopen(3X)] both return pointers to an LDFILE structure. 

Additional access to an object file is provided through a set of macros 
defined in ldfcn.h. These macros parallel the standard input/output file 
reading and manipulating functions, translating a reference of the LDFILE 
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Structure into a reference to its file descriptor field. 

The following macros are provided: 

GETC(ldptr) 
FGETC(ldptr) 
GETW(ldptr) 
UNGETC(c, Idptr) 
FGETS(s, n, Idptr) 

FREAD((char *) ptr, sizeof (*ptr), nitems, Idptr) 

FSEEK(ldptr, offset, ptrname) 

FTELL(ldptr) 

REWIND(ldptr) 

FEOF(ldptr) 

FERROR(ldptr) 

FILENO(ldptr) 

SETBUF(ldptr, buf) 

STROFFSET(ldptr) 

The STROFFSET macro calculates the address of the string table. See the 
manual entries for the corresponding standard input/output library func- 
tions for details on the use of the rest of the macros. 

The program must be loaded with the object file access routine library 
libld.a. ^ 

SEE ALSO 

fseek(3S), ldahread(3X), ldclose(3X), ldgetname(3X), ldfhread(3X), 
ldlread(3X), ldlseek(3X), ldohseek(3X), ldopen(3X), ldrseek(3X), ldlseek(3X), 
ldshread(3X), ldtbindex(3X), ldtbread(3X), ldtbseek(3X), stdio(3S), intro(5). 
WARNING 

The macro FSEEK defined in the header file Idf cn.h translates into a call to 
the standard input/output function fseek{3S). FSEEK should not be used to 
seek from the end of an archive file, since the end of an archive file may 
not be the same as the end of one of its object file members! 
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NAME 

limits - file header for implementation-specific constants 

SYNOPSIS 

#include <limits.h> 

DESCRIPTION 

The header file <limits.h> is a list of magnitude limitations imposed by a 
specific implementation of the operating system. All values are specified in 
decimal. 



#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 



ARG__MAX 

CHAR_BIT 

CHAR_MAX 

CHAR_MIN 

CHILD_MAX 

CLK_TCK 

DBL_DIG 

DBL MAX 



#define DBL_MIN 



#def ine 
#def ine 
#def ine 



FCHR_MAX 
FLT_DIG 
FLT MAX 



#define FLT_MIN 



#define HUGE_VAL 



#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 

#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 
#def ine 



INT_MAX 2 

INT_MIN - 

LINK_MAX 

LONG_MAX 

LONG_MIN 

NAME_MAX 

OPEN_MAX 

PASS_MAX 

PATH_MAX 

PID_MAX 

PIPE_BUF 

PIPE_MAX 

SHRT_MAX 

SHRT_MIN 

STD_BLK 

SYS_NMLN 

UID_MAX 

USI_MAX 

WORD BIT 



5120 /* max length of arguments to exec ♦/ 
8 /* # of bits in a "char" */ 

127 /♦ max integer value of a "char" */ 
-128 /♦ min integer value of a "char" */ 
25 /♦ max # of processes per user id */ 

100 /♦ # of clock ticks per second */ 
16 /* digits of precision of a "double" */ 

1 . 797693 1 348623 1470e+308 /*max decimal value of a 

"double"*/ 

4 . 94065645841246544e-324 /*min decimal value of a 

"double"*/ 

1048576 /* max size of a file in bytes */ 

7 /* digits of precision of a "float" */ 

3 . 40282346638528860e+38 /*max decimal value of a 

"float" */ 

1 . 40 129846432481707e-45 /*min decimal value of a 

"float" ♦/ 

3 . 40282346638528860e+38 /*error value returned by 

Math lib*/ 

147483647 /* max decimal value of an "int" */ 
2147483648 /* min decimal value of an "int" */ 
1000 /* max # of links to a single file */ 
2 147483647 /* max decimal value of a "long" */ 
-2 147483648 /* min decimal value of a "long" */ 



14 /* max # of characters in a file name */ 

60 /* max # of files a process can have open */ 

8 /* max # of characters in a password */ 
256 /♦ max # of characters in a path name */ 
30000 /* max value for a process ID */ 

5120 /* max # bytes atomic in write to a pipe */ 
5120 /* max # bytes written to a pipe 

in a write */ 
32767 /* max decimal value of a "short" */ 
-32768 /♦ min decimal value of a "short" */ 
1024 /* # bytes in a physical I/O block */ 

9 /* # of chars in uname-returned strings */ 
60000 /* max value for a user or group ID */ 
4294967295 /* max decimal value of an "unsigned" 
32 /* # of bits in a "word" or "int" */ 
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NAME 

linenum - line number entries in a common object file 

SYNOPSIS 

#include <linenum.h> 

DESCRIPTION 

The cc command generates an entry in the object file for each C source line 
on which a breakpoint is possible [when invoked with the -g option; see 
cc(l)]. Users can then reference line numbers when using the appropriate 
software test system [see sdb(l)]. The structure of these line number entries 
appears below. 

struct lineno 

{ 

union 

{ 

long l_symndx ; 

long Lpaddr ; 

} l_addr ; 

unsigned short l_lnno ; 



Numbering starts with one for each function. The initial line number entry 
for a function has l—lnno equal to zero, and the symbol table index of the 
function's entry is in Isymndx. Otherwise, IJinno is non-zero, and l^paddr 
is the physical address of the code for the referenced line. Thus the overall 
structure is the following: 



l^ddr l^lnno 

function symtab index 

physical address line 

physical address line 

function symtab index 

physical address line 

physical address line 



SEE ALSO 

cc(l), sdb(l), a.out(4). 
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NAME 

/usr/adm/loginlog - log of failed login attempts 
DESCRIPTION 

After five unsuccessful login attempts, all the attempts are logged in the 
loginlog file. This file contains one record for each failed attempt. Each 
record contains the following information: 

login name 
tty specification 
time 

This is an ASCII file. Each field within each entry is separated from the next 
by a colon. Each entry is separated from the next by a new-line. 

By default, loginlog does not exist, so no logging is done. To enable log- 
ging, the log file must be created with read and write permission for owner 
only. Owner must be root and group must be sys. 

FILES 

/usr /adm /loginlog 
SEE ALSO 

login(l), passwd(l), passwd(lM) in the User's /System Administrator's Refer- 
ence Manual, 
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NAME 

mdevice - file format. 

SYNOPSIS 

mdevice 

DESCRIPTION 

The mdevice file is included in the directory /etc/conf/cfJ. It includes a 
one-line description of each device driver and configurable software module 
in the system to be built [except for file system types, see mfsys{4)]. Each 
line in mdevice represents the Master file component from a Driver Software 
Package (DSP) either delivered with the base system or installed later via 
idinstall. 

Each line contains several whitespace-separated fields; they are described 
below. Each field must be supplied with a value or a (dash). 

1. Device name: This field is the internal name of the device or module, 
and may be up to 8 characters long. The first character of the name 
must be an alphabetic character; the others may be letters, digits, or 
underscores. 

2. Function list: This field is a string of characters that identify driver 
functions that are present. Using one of the characters below requires 
the driver to have an entry point (function) of the type indicated. If 



a dash. 




o - 


open routine 


c - 


close routine 


r - 


read routine 


w - 


write routine 


i - 


ioctl routine 


s - 


startup routine 


X - 


exit routine 


f- 


fork routine 


e - 


exec routine 


I- 


init routine 


h- 


halt routine 


P- 


poll routine 


fi- 


enter routine 


x- 


exit routine 



Note that if the device is a 'block' type device (see field 3. below), a 
strategy routine and a print routine are required by default. 

3. Characteristics of driver: This field contains a set of characters that 
indicate the characteristics of the driver. If none of the characters 
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below apply, the field should contain a dash. The legal characters for 
this field are: 

i - The device driver is installable, 

c - The device is a 'character' device, 

b - The device is a 'block' device, 

t - The device is a tty. 

o - This device may have only one sdevice entry. 

r - This device is required in all configurations of the Kernel. 
This option is intended for drivers delivered with the base 
system only. Device nodes (special files in the /dev direc- 
tory), once made for this device, are never removed. See 
idmknod. 

S - This device driver is a STREAMS module. 

H - This device driver controls hardware. This option distin- 
guishes drivers that support hardware from those that are 
entirely software (pseudo-devices). 

G - This device does not use an interrupt though an interrupt is 
specified in the sdevice entry. This is used when you wish to 
associate a device to a specific device group. 

D - This option indicates that the device driver can share its DMA 
channel. 

O - This option indicates that the lOA range of this device may 
overlap that of another device. 

4. Handler prefix: This field contains the character string prepended to all 
the externally-known handler routines associated with this driver. The 
string may be up to 4 characters long. 

5. Block Major number: This field should be set to zero in a DSP Master 
file. If the device is a 'block' type device, a value will be assigned by 
idinstall during installation. 

6. Character Major number: This field should be set to zero in a DSP 
Master file. If the device is a 'character' type device (or 'STREAMS' 
type), a value will be assigned by idinstall during installation. 

7. Minimum units: This field is an integer specifying the minimum 
number of these devices that can be specified in the sdevice file. 

8. Maximum units: This field specifies the maximum number of these 
devices that may be specified in the sdevice file. It contains an integer. 

9. DMA channel: This field contains an integer that specifies the DMA 
channel to be used by this device. If the device does not use DMA, 
place a '-1' in this field. Note that more than one device can share a 
DMA channel (previously disallowed). 



- 2 - 



MDEVICE(4) 



MDEVICE(4) 



SPECIFYING STREAMS DEVICES AND MODULES 

STREAMS modules and drivers are treated in a slightly different way from 
other drivers in all UNIX systems, and their configuration reflects this differ- 
ence. To specify a STREAMS device driver, its mdevice entry should con- 
tain both an 'S' and a 'c' in the characteristics field (see 3. above). This indi- 
cates that it is a STREAMS driver and that it requires an entry in the UNIX 
kernel's cdevsw table, where STREAMS drivers are normally configured into 
the system. 

A STREAMS module that is not a device driver, such as a line discipline 
module, requires an 'S' in the characteristics field of its mdevice file entry, 
but should not include a 'c', as a device driver does. 
SEE ALSO 

mfsys(4), sdevice(4). 

idinstall(lm) in the User's/System Administrator's Reference Manual. 
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NAME 

mfsys - file format. 

SYNOPSIS 

mfsys 

DESCRIPTION 

The mfsys file contains configuration information for file system types that 
are to be included in the next system kernel to be built. It is included in the 
directory /etc/conf/cf.d, and includes a one-line description of each file sys- 
tem type. The mfsys file is coalesced from component files in the directory 
/etc/conf/mfsys.d. Each line contains the following whitespace-separated 
fields: 

1. name: This field contains the internal name for the file system type 
(e.g., 85 IK, DUFST). This name is no more than 32 characters long, 
and by convention is composed of uppercase alphanumeric characters. 

2. prefix: The prefix in this field is the string prepended to the fstypsw 
handler functions defined for this file system type (e.g., s5, du). The 
prefix must be no more that 8 characters long. 

3. flags: The flags field contains a hex number of the form "OxNN" to 
be used in populating the fsinfo data structure table entry for this file 
system type. 

4. notify flags: The notify flags field contains a hex number of the form 
"OxNN" to be used in population the fsinfo data structure table entry 
for this file system type. 

5. function bitstring: The function hitstring is a string of 28 O's and I's. 
Each file system type potentially defines 28 functions to populate the 
fstypsw data structure table entry for itself. All file system types do 
not supply all the functions in this table, however, and this bitstring is 
used to indicate which of the functions are present and which are 
absent. A '1' in this string indicates that a function has been supplied, 
and a '0' indicates that a function has not been supplied. Successive 
characters in the string represent successive elements of the fstypsw 
data structure, with the first entry in this data structure represented by 
the rightmost character in the string. 

SEE ALSO 

sfsys(4). 

idinstall(lm), idbuild(lm) in the User's/System Administrator's Reference 
Manual. 
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NAME 

mnttab - mounted file system table 

SYNOPSIS 

#include <mnttab.h> 

DESCRIPTION 

mnttab resides in directory /etc and contains a table of devices, mountec 
the mount{lM) command, in the following structure as defined 
<mnttab.h>: 



Each entry is 70 bytes in length; the first 32 bytes are the null-padded name 
of the place where the special file is mounted; the next 32 bytes represent 
the null-padded root name of the mounted special file; the remaining 6 
bytes contain the mounted special file's read/write permissions and the date 
on which it was mounted. 

The maximum number of entries in mnttab is based on the system parame- 
ter NMOUNT, which defines the number of allowable mounted special files. 
SEE ALSO 

mount(lM), setmnt(lM) in the User's/System Administrator's Reference 
Manual. 



struct 



mnttab { 



char 
char 
short 



mt_dev[32]; 
mt_JFilsys[32]; 
mt_ro_ilg; 
mt_time; 



time_t 
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NAME 

mtune - file format. 

SYNOPSIS 

mtune 

DESCRIPTION 

The mtune file contains information about all the system tunable parame- 
ters. Each tunable parameter is specified by a single line in the file, and 
each line contains the following whitespace-separated set of fields: 

1. parameter name: A character string no more than 20 characters long. 
It is used to construct the preprocessor "#define's" that pass the value 
to the system when it is built. 

2. default value: This is the default value of the tunable parameter. If 
the value is not specified in the stune file, this value will be used when 
the system is built. 

3. minimum value: This is the minimum allowable value for the tunable 
parameter. If the parameter is set in the stune file, the configuration 
tools will verify that the new value is equal to or greater than this 
value, 

4. maximum value: This is the maximum allowable value for the tunable 
parameter. If the parameter is set in the stune file, the configuration 
tools will check that the new value is equal to or less than this value. 

The file mtune normally resides in /etc/conf/cf.d. However, a user or an 
add-on package should never directly edit the mtune file to change the set- 
ting of a system tunable parameter. Instead the idtune command should be 
used to modify or append the tunable parameter to the stune file. 

In order for the new values to become effective, the UNIX system kernel 
must be rebuilt and the system must then be rebooted. 

SEE ALSO 

stune(4). 

idbuild(lm), idtune(lm) in the Usefs/System Administrator's Reference 
Manual. 
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NAME 

passwd - password file 

DESCRIPTION 

passwd contains for each user the following information: 

login name 

password and (optional) aging 
numerical user ID 
numerical group ID 

GCOS job number, box number, optional GCOS user ID 
initial working directory 
program to use as shell 

This is an ASCII file. Each field within each user's entry is separated from 
the next by a colon. The GCOS field is used only when communicating 
with that system, and in other installations can contain any desired informa- 
tion. Each user is separated from the next by a new-line. If the shell field 
is null, /bin/sh is used. 

This file has user login information, and has general read permission. It can 
therefore be used, for example, to map numerical user IDs to names. 

The password field consists of the character x if there is a /etc/shadow file. 
If /etc/shadow does not exist and the login does have a password, this 
field will contain an encrypted copy of the password. This field remains 
only for compatibility reasons when /etc/shadow exists. 

The encrypted password consists of 13 characters chosen from a 64- 
character alphabet (., /, 0-9, A-Z, a-z) except when the password is null, in 
which case the encrypted password is also null. Password aging is effected 
for a particular user if his enoypted password in the password file is fol- 
lowed by a comma and a non-null string of characters from the above 
alphabet. (Such a string must be introduced in the first instance by the 
super-user.) 

The first character of the age, M say, denotes the maximum number of 
weeks for which a password is valid. A user who attempts to login after his 
password has expired will be forced to supply a new one. The next charac- 
ter, m say, denotes the minimum period in weeks that must expire before 
the password may be changed. The remaining characters define the week 
(counted from the beginning of 1970) when the password was last changed. 
(A null string is equivalent to zero.) M and m have numerical values in the 
range 0-63 that correspond to the 64-character alphabet shown above (i.e., 
/ = 1 week; z = 63 weeks). If m = M = (derived from the string . or ..) 
the user will be forced to change his password the next time he logs in (and 
the "age" will disappear from his entry in the password file). If w > M 
(signified, for example, by the string ./) only the super-user will be able to 
change the password. 

FILES 

/etc/passwd 
/etc/shadow 
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SEE ALSO 

getpwent(3C), group(4). 

login(l), passwd(l), and passwd(lM) in the User's/System Administrators 
Reference Manual 
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NAME 

plot - graphics interface 
DESCRIPTION 

Files of this format are produced by routines described in plot{3X) and are 
interpreted for various devices by commands described in tplot(lG). A 
graphics file is a stream of plotting instructions. Each instruction consists of 
an ASCII letter usually followed by bytes of binary information. The 
instructions are executed in order. A point is designated by four bytes 
representing the x and y values; each value is a signed integer. The last 
designated point in an 1, m, n, or p instruction becomes the "current point" 
for the next instruction. 

Each of the following descriptions begins with the name of the correspond- 
ing routine in plot{3X). 

m move: The next four bytes give a new current point. 

n cont: Draw a line from the current point to the point given by the next 
four bytes [see tplot{lG)]. 

p point: Plot the point given by the next four bytes. 

1 line: Draw a line from the point given by the next four bytes to the 
point given by the following four bytes. 

t label: Place the following ASCII string so that its first character falls on 
the current point. The string is terminated by a new-line. 

e erase: Start another frame of output. 

f linemod: Take the following string, up to a new-line, as the style for 
drawing further lines. The styles are "dotted", "solid", "longdashed", 
"shortdashed", and "dotdashed". Effective only for the -T4014 and 
-Tver options of tplot(lG) (TEKTRONIX 4014 terminal and VERSATEC 
plotter). 

s space: The next four bytes give the lower left comer of the plotting area; 
the following four give the upper right corner. The plot will be magni- 
fied or reduced to fit the device as closely as possible. 

Space settings that exactly fill the plotting area with unity scaling appear 
below for devices supported by the filters of tplot{lG). The upper limit is 
just outside the plotting area. In every case the plotting area is taken to be 
square; points outside may be displayable on devices whose face is not 
square. 

DASI 300 -spaceCO, 0, 4096, 4096); 

DASI 300s space(0, 0, 4096, 4096); 

DASI 450 space(0, 0, 4096, 4096); 

TEKTRONIX 4014 space(0, 0, 3120, 3120); 
VERSATEC plotter space(0, 0, 2048, 2048); 

SEE ALSO 

plot(3X), term(5). 

graph(lG), tplot(lG) in the Usefs/System Administrator's Reference Manual 
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WARNING 

The plotting library plot(3X) and the curses library curses{3X) both use the 
names erase() and move(). The curses versions are macros. If you need 
both libraries, put the plot{3X) code in a different source file than the 
curses{3X) code, and/or #undef move() and erase() in the plot(3X) code. 
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NAME 

pnch - file format for card images 
DESCRIPTION 

The PNCH format is a convenient representation for files consisting of card 
images in an arbitrary code. 

A PNCH file is a simple concatenation of card records. A card record con- 
sists of a single control byte followed by a variable number of data bytes. 
The control byte specifies the number (which must lie in the range 0-80) of 
data bytes that follow. The data bytes are 8-bit codes that constitute the 
card image. If there are fewer than 80 data bytes, it is understood that the 
remainder of the card image consists of trailing blanks. 
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NAME 

profile - setting up an environment at login time 

SYNOPSIS 

/etc/profile 
$HOME/.profile 

DESCRIPTION 

All users who have the shell, sh(l), as their login command have the com- 
mands in these files executed as part of their login sequence. 

/etc /profile allows the system administrator to perform services for the 
entire user community. Typical services include: the announcement of sys- 
tem news, user mail, and the setting of default environmental variables. It 
is not unusual for /etc /profile to execute special actions for the root login or 
the sm(1M) command. Computers running outside the Eastern time zone 
should have the line 



. /etc/TIMEZONE 



included early in /etc /profile [see timezone(4)]. 

The file $HOME / .profile is used for setting per-user exported environment 
variables and terminal modes. The following example is typical (except for 
the comments): 

# Make some environment variables global 
export MAIL PATH TERM 

# Set file creation mask 
umask 027 

# Tell me when new mail comes in 
MAIL= /usr/mail/$LOGNAME 

# Add my /bin directory to the shell search sequence 
PATH=$PATH:$HOME /bin 

# Set terminal type 
while : 

do echo "terminal: \c" 

read TERM 

if [ -f ${TERMINFO:-/usr/lib/terminfo}/?/$TERM ] 
then break 

elif [ -f /usr/lib/terminfo/?/$TERM ] 
then break 

else echo " invalid term $TERM " 1>&2 
fi 

done 

# Initialize the terminal and set tabs 

# The environmental variable TERM must have been exported 

# before the "tput init" command is executed, 
tput init 

# Set the erase character to backspace 
stty erase ' H' echoe 



- 1 - 



PROFILE(4) 



PROFILE(4) 



HLES 

/etc/TIMEZONE timezone environment 

$HOME/.profile user-specific environment 

/etc/profile system-wide environment 

SEE ALSO 

terminfo(4), timezone(4), environ(5), term(5). 

env(l), login(l), maa(l), sh(l), stty(l), su(lM), tput(l) in the User's/System 
Administrator's Reference Manual 

User's Guide. 

Programmer's Guide. 

NOTES 

Care must be taken in providing system-wide services in /etc /profile. Per- 
sonal .profile files are better for serving all but the most global needs. 
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NAME 

reloc - relocation information for a common object file 

SYNOPSIS 

#include <reloc.h> 

DESCRIPTION 

Object files have one relocation entry for each relocatable reference in the 
text or data. If relocation information is present, it will be in the following 
format. 

struct reloc 

{ 

long 

long 
short 

}; 

# define R_JPCRLONG 



r_vaddr ; /* (virtual) address of 

reference */ 
r__symndx ; /* index into symbol table */ 
r-_type ; /* relocation type */ 

024 



As the link editor reads each input section and performs relocation, the relo- 
cation entries are read. They direct how references found vdthin the input 
section are treated. 

R_PCRLONG A "PC-relative" 32-bit reference to the symbol's virtual 
address. 

More relocation types exist for other processors. Equivalent relocation types 
on different processors have equal values and meanings. New relocation 
types will be defined (vdth new values) as they are needed. 

Relocation entries are generated automatically by the assembler and 
automatically used by the link editor. Link editor options exist for both 
preserving and removing the relocation entries from object files. 

SEE ALSO 

as(l), ld(l), a.out(4), syms(4). 
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NAME 

rfmaster - Remote File Sharing name server master file 
DESCRIPTION 

The rfmaster file is an ASCII file that identifies the hosts that are responsi- 
ble for providing primary and secondary domain name service for Remote 
File Sharing domains. This file contains a series of records, each terminated 
by a new-line; a record may be extended over more than one line by escap- 
ing the new-line character with a backslash ("\"). The fields in each record 
are separated by one or more tabs or spaces. Each record has three fields: 
name type data 

The type field, which defines the meaning of the name and data fields, has 
three possible values: 

p The p type defines the primary domain name server. For this type, 
name is the domain name and data is the full host name of the 
machine that is the primary name server. The full host name is 
specified as domain.nodename. There can be only one primary name 
server per domain. 

s The s type defines a secondary name server for a domain. Name and 
data are the same as for the p type. The order of the s entries in the 
rfmaster file determines the order in which secondary name servers 
take over when the current domain name server fails. 

a The a type defines a network address for a machine. Name is the full 
domain name for the machine and data is the network address of the 
machine. The network address can be in plain ASCII text or it can be 
preceded by a \x to be interpreted as hexadecimal notation. (See the 
documentation for the particular network you are using to determine 
the network addresses you need.) 

There are at least two lines in the rfmaster file per domain name server: 
one p and one a line, to define the primary and its network address. There 
should also be at least one secondary name server in each domain. 

This file is created and maintained on the primary domain name server. 
When a machine other than the primary tries to start Remote File Sharing, 
this file is read to determine the address of the primary. If rfmaster is miss- 
ing, the -p option of rfstart must be used to identify the primary. After 
that, a copy of the primary's rfmaster file is automatically placed on the 
machine. 

Domains not served by the primary can also be listed in the rfmaster file. 
By adding primary, secondary, and address information for other domains 
on a network, machines served by the primary will be able to share 
resources with machines in other domains. 

A primary name server may be a primary for more than one domain. How- 
ever, the secondaries must then also be the same for each domain served by 
the primary. 
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EXAMPLES 

An example of an rfmaster file is shown below. (The network address 
examples, compl. serve and Compuserve, are STARLAN network addresses.) 

CCS p CCS. compl 

CCS s ccs.comp2 

ccs.comp2 a comp2.serve 

ccs.compl a compl. serve 

NOTE: If a line in the rfmaster file begins with a # character, the entire 
line will be treated as a comment. 



FILES 



/usr /nserve /rfmaster 



SEE ALSO 

rfstart(lM) in the User's/System Administratofs Reference Manual. 
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NAME 

sccsfile - format of SCCS file 
DESCRIPTION 

An SCCS (Source Code Control System) file is an ASCII file. It consists of 
six logical parts: the checksum, the delta table (contains information about 
each delta), user names (contains login names and/or numerical group IDs 
of users who may add deltas), flags (contains definitions of internal key- 
words), comments (contains arbitrary descriptive information about the file), 
and the body (contains the actual text lines intermixed with control lines). 

Throughout an SCCS file there are lines which begin with the ASCn SOH 
(start of heading) character (octal 001). This character is hereafter referred 
to as the control character and will be represented graphically as @. Any 
line described below which is not depicted as beginning with the control 
character is prevented from beginning with the control character. 

Entries of the form DDDDD represent a five-digit string (a number between 
00000 and 99999). 

Each logical part of an SCCS file is described in detail below. 
Checksum 

The checksum is the first line of an SCCS file. The form of the line 
is: 

@hDDDDD 

The value of the checksum is the sum of all characters, except those 
of the first line. The @h provides a magic number of (octal) 
064001. 

Delta table 

The delta table consists of a variable number of entries of the form: 

@S DDDDD/DDDDD/DDDDD 

@d <type> <SCCS ID> yr/mo/da hr:mi:se <pgmr> DDDDD DDDDD 
@i DDDDD ... 
@X DDDDD ... 
@g DDDDD ... 
@m <MR number> 



@c <comments> ... 



@e 

The first line (@s) contains the number of lines 
inserted/deleted/unchanged, respectively. The second line (@d) 
contains the type of the delta (currently, normal: D, and removed: 
R), the SCCS ID of the delta, the date and time of creation of the 
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delta, the login name corresponding to the real user ID at the time 
the delta was created, and the serial numbers of the delta and its 
predecessor, respectively. 

The @i, @x, and @g lines contain the serial numbers of deltas 
included, excluded, and ignored, respectively. These lines are 
optional. 

The @m lines (optional) each contain one MR number associated 
with the delta; the @c lines contain comments associated with the 
delta. 

The @e line ends the delta table entry. 
User names 

The list of login names and/or numerical group IDs of users who 
may add deltas to the file, separated by new-lines. The lines con- 
taining these login names and/or numerical group IDs are sur- 
rounded by the bracketing lines @u and @U. An empty list allows 
anyone to make a delta. Any line starting with an ! prohibits the 
succeeding group or user from making deltas. 

Flags 

Keywords used internally. [See admin(l) for more information on 
their use.] Each flag line takes the form: 

@f <flag> <optional text> 

The following flags are defined: 

@f t <type of program> 

@f V <program name> 

@f i <keyword string> 
@f b 

@f m <module name> 

@f f <floor> 

@f c <ceiling> 

@f d <default-sid> 
@f n 
@fj 

@f 1 <lock-releases> 

@f q <user defined> 

@f z <reserved for use in interfaces> 

The t flag defines the replacement for the %Y% identification key- 
word. The V flag controls prompting for MR numbers in addition to 
comments; if the optional text is present it defines an MR number 
validity checking program. The i flag controls the warning/error 
aspect of the "No id keywords" message. When the i flag is not 
present, this message is only a warning; when the i flag is present, 
this message will cause a "fatal" error (the file will not be gotten, or 
the delta will not be made). When the b flag is present the -b 



- 2 - 



SCCSFILE(4) 



SCCSFILE(4) 



keyletter may be used on the get command to cause a branch in the 
delta tree. The m flag defines the first choice for the replacement 
text of the %M% identification keyword. The f flag defines the 
"floor" release; the release below which no deltas may be added. 
The c flag defines the "ceiling" release; the release above which no 
deltas may be added. The d flag defines the default SID to be used 
when none is specified on a get command. The n flag causes delta 
to insert a "null" delta (a delta that applies no changes) in those 
releases that are skipped when a delta is made in a new release 
(e.g., when delta 5.1 is made after delta 2.7, releases 3 and 4 are 
skipped). The absence of the n flag causes skipped releases to be 
completely empty. The j flag causes get to allow concurrent edits of 
the same base SID. The 1 flag defines a list of releases that are 
locked against editing lget{l) with the -e keyletter]. The q flag 
defines the replacement for the %Q% identification keyword. The z 
flag is used in certain specialized interface programs. 

Comments 

Arbitrary text is surrounded by the bracketing lines @t and @T. 
The comments section typically will contain a description of the 
file's purpose. 

Body 

The body consists of text lines and control lines. Text lines do not 
begin with the control character; control lines do. There are three 
kinds of control lines: insert, delete, and end, represented by: 

@I DDDDD 
@D DDDDD 
@E DDDDD 

respectively. The digit string is the serial number corresponding to 
the delta for the control line. 

SEE ALSO 

admin(l), delta(l), get(l), prs(l). 
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NAME 

scnhdr - section header for a common object file 

SYNOPSIS 

#include <scnhdr.h> 

DESCRIPTION 

Every common object file has a table of section headers to specify the lay- 
out of the data within the file. Each section within an object file has its 
own header. The C structure appears below. 



struct 

{ 



scnhdr 

char 
long 
long 
long 
long 
long 
long 



} 



s_paddr; 
s_vaddr; 
s_size; 
s_scnptr; 
s_relptr; 
s_lnnoptr; 
unsigned short s__nreloc; 
unsigned short s_nlnno; 
long s_flags; 



s_name[SYMNMLEN]; /* section name */ 



/* physical address */ 
/* virtual address */ 
/* section size */ 
/* file ptr to raw data */ 
/* file ptr to relocation */ 
/* file ptr to line numbers */ 
/* # reloc entries */ 
/* # line number entries */ 
/* flags */ 



File pointers are byte offsets into the file; they can be used as the offset in a 
call to FSEEK [see ldfcn{4)]. If a section is initialized, the file contains the 
actual bytes. An uninitialized section is somewhat different. It has a size, 
symbols defined in it, and symbols that refer to it. But it can have no relo- 
cation entries, line numbers, or data. Consequently, an uninitialized section 
has no raw data in the object file, and the values for sscnptr, s^relptr, 
S—lnnoptr, S—tireloc, and s_n/nno are zero. 

SEE ALSO 

ld(l), fseek(3S), a.out(4). 
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NAME 

scr_dump - format of curses screen image file. 

SYNOPSIS 

scr_dump(file) 

DESCRIPTION 

The curses{3X) function scr—dump{) will copy the contents of the screen into 
a file. The format of the screen image is as described below. 

The name of the tty is 20 characters long and the modification time (the 
mtime of the tty that this is an image of) is of the type time—t. All other 
numbers and characters are stored as chtype (see <curses.h>). No new- 
lines are stored between fields. 



<magic number: octal 0433> 
<name of tty> 
<mod time of tty> 
<columns> <lines> 

<line length> <chars in line> for each line on the screen 

<line length> <chars in line> 



<labels?> 1, if soft screen labels are present 

<cursor row> <cursor column> 

Only as many characters as are in a line will be listed. For example, if the 
<line length> is 0, there will be no characters following <line length>. If 
<labels?> is TRUE, following it will be 

<number of labels> 
<label width> 
<chars in label 1> 
<chars in label 2> 



SEE ALSO 

curses(3X). 
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NAME 

sdevice - file format. 

SYNOPSIS 

sdevice 

DESCRIPTION 

The sdevice file contains local system configuration information for each of 
the devices specified in the mdevice file. It contains one or more entries for 
each device specified in mdevice. Sdevice is present in the directory 
/etc/conf/cf.d, and is coalesced from component files in the directory 
/etc/conf/sdevice.d. Files in / etc /conf/ sdevice. d are the System file com- 
ponents either delivered with the base system or installed later via idinstall. 

Each entry must contain the following whitespace-separated fields: 

1. Device name: This field contains the internal name of the driver. This 
must match one of the names in the first field of an mdevice file entry. 

2. Configure: This field must contain the character 'Y' indicating that the 
device is to be installed in the kernel. For testing purposes, an 'N' 
may be entered indicating that the device will not be installed. 

3. Unit: This field can be encoded with a device dependent numeric 
value. It is usually used to represent the number of subdevices on a 
controller or pseudo-device. Its value must be within the minimum 
and maximum values specified in fields 7 and 8 of the mdevice entry. 

4. Ipl: The ipl field specifies the system ipl level at which the driver's 
interrupt handler will run in the new system kernel. Legal values are 
through 8. If the driver doesn't have an interrupt handling routine, 
put a in this field. 

5. Type: This field indicates the type of interrupt scheme required by the 
device. The permissible values are: 

- The device does not require an interrupt line. 

1 - The device requires an interrupt line. 

If the driver supports more than one hardware controller, each 
controller requires a separate interrupt. 

2 - The device requires an interrupt line. 

If the driver supports more than one hardware controller, each 
controller will share the same interrupt. 

3 - The device requires an interrupt line. 

If the driver supports more than one hardware controller, each 
controller will share the same interrupt. Multiple device 
drivers having the same ipl level can share this interrupt. 

6. Vector: This field contains the interrupt vector number used by the 
device. If the Type field contains a (i.e., no interrupt required), this 
field should be encoded with a 0. Note that more than one device can 
share an interrupt number. 



- 1 - 



SDEVICE(4) 



SDEVICE(4) 



7. SIOA: The SIOA field (Start I/O Address) contains the starting address 
on the I/O bus through which the device communicates. This field 
must be within 0x1 and 0x3fff. (If this field is not used, it should be 
encoded with the value zero.) 

8. EIOA: The field (End I/O Address) contains the end address on the 
I/O bus through which the device communicates. This field must be 
within 0x1 and 0x3fff. (If this field is not used, it should be encoded 
with the value zero.) 

9. SCMA: The SCMA field (Start Controller Memory Address) is used by 
controllers that have internal memory. It specifies the starting address 
of this memory. This field must be within OxaOOOO and Oxfbfff. (If 
this field is not used, it should be encoded with the value zero.) 

10. ECMA: The ECMA (End Controller Memory Address) specifies the end 
of the internal memory for the device. This field must be within 
OxaOOOO and Oxfbfff. (If this field is not used, it should be encoded 
with the value zero.) 

SEE ALSO 

mdevice(4). 

idinstall(lm) in the User's /System Administrator's Reference Manual. 
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NAME 

sfsys - file format. 

SYNOPSIS 

sfsys 

DESCRIPTION 

The sfsys file contains local system information about each file system type 
specified in the mfsys file. It is present in the directory /etc/conf/cf.d, and 
contains a one-line entry for each file system type specified in the mfsys file. 
The sfsys file is coalesced from component files in the directory 
/etc/conf/sfsys.d. Each line in this file is a whitespace-separate set of fields 
that specify: 

1. name: This field contains the internal name of the file system type 
(e.g., DUFST, 85 IK). By convention, this name is up to 32 characters 
long, and is composed of all uppercase alphanumeric characters. 

2. y/N: This field contains either an uppercase 'Y' (for "yes") or an 
uppercase 'N' (for "no) to indicate whether the named file system 
type is to be configured into the next system kernel to be built. 

SEE ALSO 

mfsys(4). 

idinstall(lm), idbuild(lm) in the User's /System Administrator's Reference 
Manual, 
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NAME 

stune - file format. 

SYNOPSIS 

stune 

DESCRIPTION 

The stune file contains local system settings for tunable parameters. The 
parameter settings in this file replace the default values specified in the 
mtune file, if the new values are within the legal range for the parameter 
specified in mtune. The file contains one line for each parameter to be reset. 
Each line contains two whitespace-separated fields: 

1. external name: This is the external name of the tunable parameter 
used in the mtune file. 

2. value: This field contains the new value for the tunable parameter. 

The file stune normally resides in /etc/conf/cf.d. However, a user or an 
add-on package should never directly edit the mtune file. Instead the idtune 
command should be used. 

In order for the new values to become effective the UNIX kernel must be 
rebuilt and the system must then be rebooted. 

SEE ALSO 

mtune(4). 

idbuild(lm), idtune(lm) in the User's/System Administrator's Reference 
Manual 
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NAME 

syms - common object file symbol table format 

SYNOPSIS 

#include <syms.h> 

DESCRIPTION 

Common object files contain information to support symbolic software test- 
ing [see sdb{l)]. Line number entries, linenum{4), and extensive s)m[ibolic 
information permit testing at the C source level. Every object file's symbol 
table is organized as shown below. 



File name 1. 

Function 1. 

Local symbols for function 1. 
Function 2. 

Local symbols for function 2. 

Static extems for file 1. 

File name 2. 

Function 1. 

Local symbols for function 1. 
Function 2. 

Local symbols for function 2. 

Static extems for file 2. 



Defined global symbols. 
Undefined global symbols. 



The entry for a S)niibol is a fixed-length structure. The members of the 
structure hold the name (null padded), its value, and other information. 
The C structure is given below. 

#define SYMNMLEN 8 
#define FILNMLEN 14 
#define DIMNUM 4 

struct syment 



union 



/* all ways to get symbol name */ 



char 
struct 



_n_name[SYMNMLEN]; /* symbol name */ 



{ 

long 
long 



__n__zeroes; 
_n_offset; 



/* == OL when in string table */ 
/* location of name in table */ 



} -n-n; 
char 



*_n_nptr[2]; 



/* allows overlaying */ 
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long 
short 

unsigned short 

char 

char 

}; 

#define n__name 
#define rL_zeroes 
#define n_offset 
#define n__nptr 



n_value; /* value of symbol */ 

n_scnum; /* section number */ 

n-_type; /* type and derived type */ 

n_-sclass; /* storage class */ 

n_jiumaux; /* number of aux entries */ 



_n._n-_name 

-Ji — n__n n__zeroes 

_n — n_n n_offset 

_n._n-_nptr[l] 



Meaningful values and explanations for them are given in both syms.h and 
Common Object File Format, Anyone who needs to interpret the entries 
should seek more information in these sources. Some symbols require more 
information than a single entry; they are followed by auxiliary entries that 
are the same size as a symbol entry. The format follows. 

union auxent 

{ 

struct 

{ 



long 
union 

{ 



struct 

{ 



-tagndx; 



unsigned short x_Jnno; 
unsigned short x_size; 



} x_misc; 
union 

{ 



} x_lnsz; 
long x_fsize; 



struct 

{ 



} 

struct 

{ 



long x_lnnoptr; 
long x_endndx; 
x_fcn; 



} 



} 

struct 

{ 
} 



} 

unsigned short x— tvndx; 



unsigned short x_dimen[DIMNUM]; 
x^ry; 
x_fcnary; 



char x_fname[FILNMLEN]; 
x_file; 
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struct 

{ 

long x_scnlen; 
unsigned short x_nreloc; 
unsigned short x_nlinno; 
} x_scn; 

struct 

{ 

long x_tvfill; 

unsigned short x_tvlen; 

unsigned short x_tvran[2]; 
} x_tv; 

}; 

Indexes of symbol table entries begin at zero. 

SEE ALSO 

sdb(l), a.out(4), linenum(4). 

"Common Object File Format" in the Programmer's Guide, 
WARNINGS 

On machines on which ints are equivalent to longs, all longs have their 
type changed to int. Thus the information about v^hich symbols are 
declared as longs and which, as ints, does not show up in the symbol table. 
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NAME 

term - format of compiled term file. 

SYNOPSIS 

/usr/lib/terminfo/?/* 

DESCRIPTION 

Compiled terminfo{A) descriptions are placed under the /usr/lib/terminfo 
directory. In order to avoid a linear search of a huge UNIX system directory, 
a two-level scheme is used: /usr /lib /terminfo/c /name where name is the 
name of the terminal, and c is the first character of name. Thus, att4425 can 
be found in the file /usr/lib/terminfo/a/att4425. Synonyms for the same 
terminal are implemented by multiple links to the same compiled file. 

The format has been chosen so that it will be the same on all hardware. An 
8-bit byte is assumed, but no assumptions about byte ordering or sign 
extension are made. Thus, these binary terminfo{4) files can be transported 
to other hardware with 8-bit bytes. 

Short integers are stored in two 8-bit bytes. The first byte contains the least 
significant 8 bits of the value, and the second byte contains the most signifi- 
cant 8 bits. (Thus, the value represented is 256*second+first.) The value -1 
is represented by 0377,0377, and the value -2 is represented by 0376,0377; 
other negative values are illegal. Computers where this does not 
correspond to the hardware read the integers as two bytes and compute the 
result, making the compiled entries portable between machine types. The 
-1 generally means that a capability is missing from this terminal. The -2 
means that the capability has been cancelled in the terminfo{4) source and 
also is to be considered missing. 

The compiled file is created from the source file descriptions of the termi- 
nals [see the -I option of infocmp(lM)] by using the terminfo{4) compiler, 
fzc(lM), and read by the routine setupterm(). [See curses{3X).] The file is 
divided into sbc parts: the header, terminal names. Boolean flags, numbers, 
strings, and string table. 

The header section begins the file. This section contains six short integers 
in the format described below. These integers are: (1) the magic number 
(octal 0432); (2) the size, in bytes, of the names section; (3) the number of 
bytes in the Boolean section; (4) the number of short integers in the 
numbers section; (5) the number of offsets (short integers) in the strings sec- 
tion; (6) the size, in bytes, of the string table. 

The terminal names section comes next. It contains the first line of the ter- 
minfo(4) description, listing the various names for the terminal, separated by 
the bar ( I ) character [see term{5)]. The section is terminated with an ASCII 
NUL character. 

The Boolean flags have one byte for each flag. This byte is either or 1 as 
the flag is present or absent. The value of 2 means that the flag has been 
cancelled. The capabilities are in the same order as the file <term.h>. 
Between the Boolean section and the number section, a null byte will be 
inserted, if necessary, to ensure that the number section begins on an even 
byte. All short integers are aligned on a short word boundary. 
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The numbers section is similar to the Boolean flags section. Each capability 
takes up two bytes, and is stored as a short integer. If the value represented 
is -1 or -2, the capability is taken to be missing. 

The strings section is also similar. Each capability is stored as a short 
integer, in the format above. A value of -1 or -2 means the capability is 
missing. Otherwise, the value is taken as an offset from the beginning of 
the string table. Special characters in X or \c notation are stored in their 
interpreted form, not the printing representation. Padding information 
($<nn>) and parameter information (%x) are stored intact in uninterpreted 
form. 

The final section is the string table. It contains all the values of string capa- 
bilities referenced in the string section. Each string is null terminated. 

Note that it is possible for setuptenn( ) to expect a different set of capabili- 
ties than are actually present in the file. Either the database may have been 
updated since setupterm( ) has been recompiled (resulting in extra unrecog- 
nized entries in the file) or the program may have been recompiled more 
recently than the database was updated (resulting in missing entries). The 
routine setupterm( ) must be prepared for both possibilities — this is why the 
numbers and sizes are included. Also, new capabilities must always be 
added at the end of the lists of Boolean, number, and string capabilities. 

As an example, an octal dump of the description for the AT&T Model 37 
KSR is included: 

37|tty37|ATS.T nodel 37 teletype, 
he, OS, xan, 

bel='^G, cx=\r, cuib1=\b, cud1=\n, cuii1=\E7, hd=\E9, 
hu=\E8, ind=\n. 



0000000 


032 


001 




\0 032 


\0 


013 \0 


021 


001 


3 


\0 


3 


7 


1 


t 


0000020 


t 


y 


3 


7 1 


A 


T & 


T 




m 


o 


d 


e 


1 




0000040 


3 


7 




t e 


1 


e t 


y 


P 


e 


\0 


\0 


\0 


\0 


\0 


0000060 


\0 


\o 


\0 


001 \0 


\0 


\0 \0 


\0 


\0 


\0 


001 


\0 


\0 


\0 


\0 


0000100 


001 


\o 


\0 


\0 \0 


\0 


377 377 


377 


377 


377 


377 


377 


377 


377 


377 


0000120 


377 


377 


377 377 377 


377 


377 377 


377 


377 


377 


377 


377 


377 


& 


\0 


0000140 




\0 


377 


377 377 


377 


377 377 


377 


377 


377 


377 


377 


377 


377 


377 


0000160 


377 


377 


II 


\0 377 


377 


377 377 


( 


\0 


377 


377 


377 


377 


377 


377 


0000200 


377 


377 





\0 377 


377 


377 377 


377 377 


377 


377 




\0 


377 


377 


0000220 


377 


377 


377 


377 377 


377 


377 377 


377 


377 


377 


377 


377 


377 


377 


377 


♦ 

0000520 


377 


377 


377 


377 377 


377 


377 377 


377 


377 


377 


377 


377 


377 


$ 


\0 


0000540 


377 


377 


377 377 377 


377 


377 377 


377 377 


377 377 


377 


377 


* 


\0 


0000560 


377 


377 


377 


377 377 


377 


377 377 


377 


377 


377 


377 


377 


377 


377 


377 


0001160 


377 


377 


377 


377 377 


377 


377 377 


377 


377 


377 


377 


377 


377 


3 


7 


0001200 


1 


t 


t 


y 3 


7 


1 A 


T 




T 




m 


o 


d 


e 


0001220 


1 




3 


7 


t 


e 1 


e 


t 


y 


P 


e 


\0 


\r 


\0 


0001240 




\0 


\n 


\0 007 


\0 


\b \0 


033 


8 


\0 


033 


9 


\0 


033 


7 



0001260 \0 \0 
0001261 

Some limitations: total compiled entries cannot exceed 4096 bytes; all 
entries in the name field cannot exceed 128 bytes. 
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FILES 

/usr/lib/terminfo/?/* compiled terminal description database 
/usr/include/term.h terminfo{4) header file 
SEE ALSO 

curses(3X), terminfo(4), term(5). 

infocmp(lM) in the Usefs/System Administrator's Reference Manual 
Chapter 10 of the Programmer's Guide. 
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NAME 

terminfo - terminal capability data base 

SYNOPSIS 

/usr /lib /terminfo /? /* 

DESCRIPTION 

terminfo is a compiled database [see tic(lM)] describing the capabilities of termi- 
nals. Terminals are described in terminfo source descriptions by giving a set of 
capabilities which they have, by describing how operations are performed, by 
describing padding requirements, and by specifying initialization sequences. 
This database is used, for example, by vi{l) and curses(3X), so they can work 
with a variety of terminals without changes to the programs. To obtain the 
source description for a terminal, use the -I option of infocmp (IM), When doing 
an infocmp for the terminal you are on, there is no difference between infocmp 
and infocmp -1. 

Entries in terminfo source files consist of a number of fields separated by com- 
mas. White space after each comma is ignored. The first line of each terminal 
description in the terminfo database gives the name by which terminfo knows the 
terminal, separated by bar ( I ) characters. The first name given is the most 
common abbreviation for the terminal [this is the one to use to set the environ- 
ment variable TERM in $HOME/.profile; see profile{^)]; the last name given 
should be a long name fully identifying the terminal, and all others are under- 
stood as synon)n3\s for the terminal name. All names but the last should contain 
no blanks and must be unique in the first 14 characters; the last name may con- 
tain blanks for readability. 

Terminal names (except for the last verbose entry) should be chosen using the 
following conventions. The particular piece of hardware making up the terminal 
should have a root name chosen, for example, for the AT&T 4425 terminal, 
att4425. Modes that the hardware can be in, or user preferences, should be indi- 
cated by appending a hyphen and an indicator of the mode. See term{5) for 
examples and more information on choosing names and synonyms. 

PART 1: TERMINAL CAPABILITIES 

Capabilities in terminfo are of three types: boolean capabilities (which show that 
the terminal has some particular feature), numeric capabilities (which specify the 
size of the terminal or particular features), and string capabilities (which provide 
a sequence that can be used to perform particular terminal operations). 

In the following tables, a Variable is the name by which a C programmer 
accesses a capability (at the terminfo level). A Capname is the short name for a 
capability used in the source description. It is used by a person updating the 
database and by the tput(l) command when asking what the value of the capa- 
bility is for a particular terminal. A Termcap Code is a two-letter code that 
corresponds to the old termcap capability name. 

Capability names have no hard length limit, but an informal limit of five charac- 
ters has been adopted to keep them short. Whenever possible, names are 
chosen to be the same as or similar to those specified by the ANSI X3.64-1979 
standard. Semantics are also intended to match those of the ANSI standard. 
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All string capabilities listed below may have padding specified, with the excep- 
tion of those used for input. Input capabilities, listed under the Strings section 
in the following table, have names beginning with key— The following indica- 
tors may appear at the end of the Description for a variable. 

(G) indicates that the string is passed through tparm() with parameters 
(parms) as given (#p 

(*) indicates that padding may be based on the number of lines affected 

(# .) indicates the i parameter 



-2- 



TERMINFO(4) (Terminal Information Utilities) TERMINFO(4) 



Booleans 



Variable 


Cap- 


Termcap 


Description 


Page# 


name 


Code 




auto_left_margin 


bw 


bw 


cubl wraps from column to last column 


25 


auto_right__margin 


am 


am 


Terminal has automatic margins 


25 


back_color_erase 


bee 


be 


Screen erased with background color 


36 


can_change 


ccc 


cc 


Terminal can re-define existing color 


35 


ceol_standout_glitch 


xhp 


xs 


Standout not erased by overwriting (hp) 


38 


col_addr_glitch 


xhpa 


YA 


Only positive motion for hpa/mhpa caps 


42 


cpi_changes_res 


cpix 


YF 


Changing character pitch changes resolution 


40 


cr_cancels— micro_mode 


crxm 


YB 


Using cr turns off micro mode 


43 


eat_newline_glitch 


xenl 


xn 


Newline ignored after 80 columns {Concept) 


38 


erase_overstrike 


eo 


eo 


Can erase overstrikes with a blank 


31 


generic type 


gn 


gi^ 


Generic line type (e.g., dialup, switch) 


37 


l;\ard copy 


he 


he 


Hardcopy terminal 


25 


hard_cursor 


chts 


HC 


Cursor is hard to see 


30 


has meta key 


km 


km 


Has a meta key (shift, sets parity bit) 


37 


has_print_wheel 


daisy 


YC 


Printer needs operator to change character set 


46 


has_status_line 


hs 


hs 


Has extra "status line" 


34 


hue_lightness_saturation 


his 


hi 


Terminal uses only HLS color notation (Tektronbc) 


36 


insert__null glitch 


in 


in 


Insert mode distinguishes nulls 


29 


lpL_changes_res 


ipix 


YG 


Changing line pitch changes resolution 


41 


memory_above 


da 


da 


Display may be retained above the screen 


28 


memory_below 


db 


db 


Display may be retained below the screen 


28 


move insert__mode 


mir 


mi 


Safe to move while in insert mode 


29 


move_standout_mode 


msgr 


ms 


Safe to move in standout modes 


30 


needs__xon xoff 


nxon 


nx 


Padding won't work, xon/xoff required 




no_esc_ctlc 


xsb 


xb 


Beehive (fl=escape, f2=ctrl C) 


38 


no_pad char 


npc 


NP 


Pad character doesn't exist 


36 


non_dest_scrolL_region 


ndscr 


ND 


Scrolling region is non-destructive 


31 


non— rev_rmcup 


nrrmc 


NR 


smcup does not reverse rmcup 


over—Strike 


OS 


OS 


Terminal overstrikes on hard-copy terminal 


25 


prtr_silent 


mc5i 


5i 


Printer won't echo on screen 


37 


row_addr_glitch 


xvpa 


YD 


Only positive motion for vpa/mvpa caps 


42 


semi_auto_right_margin 


sam 


YE 


Printing in last column causes cr 


43 


status_line_esc_ok 


eslok 


es 


Escape can be used on the status line 


34 


dest_tabs_magic_smso 


xt 


xt 


Destructive tabs, magic smso char (tl061) 


38 


tilde—glitch 


hz 


hz 


Hazeltine; can't print tilde (") 


38 


transparent— underline 


ul 


ul 


Underline character overstrikes 


31 


xon_xoff 


xon 


xo 


Terminal uses xon/xoff handshaking 


25 



-3- 



TERMINFO(4) 



(Terminal Information Utilities) 



TERMINFO(4) 



Numbers 



Variable 


Pan. 

name 


1 erincap 
Code 


Description | 


buffer—capacity 


bufsz 


Ya 


Number of bytes buffered before printing 


columns 


cols 


CO 


Number of columns in a line 


dot_vert_spadng 


spinv 


Yb 


Spacing of pins vertically in pins per inch 


dot__horz_spacing 


spinh 


Yc 


Spacing of dots horizontally in dots per inch 


init_tabs 


it 


it 


Tabs initially every # spaces 


labeLheight 


Ih 


Ih 


Number of rows in each label 


label—width 


Iw 


Iw 


Number of columns in each label 


lines 


lines 


li 


Number of lines on a screen or a page 


lines— of_memory 


Im 


Im 


Lines of memory if > lines; means varies 


magic—cookie— glitch 


xmc 


sg 


Number of blank characters left by smso or rmso 


max—attributes 


ma 


ma 


Maximum combined video attributes terminal can display 


max_colors 


colors 


Co 


Maximum number of colors on the screen 


max_micro_address 


maddr 


Yd 


Maximum value in micro address 


max— micro— jump 


mjump 


Ye 


Maximum value in parm micro 


max— pairs 


pairs 


pa 


Maximum number of color-pairs on the screen 


maximum— windows 


wnum 


MW 


Maximum number of definable windows 


micro— col— size 


mcs 


Yf 


Character step size when in micro mode 


micro— line— size 


mis 


Yg 


Line step size when in nucro mode 


no— color— video 


ncv 


NC 


Video attributes that can't be used with colors 


number— of—pins 


npins 


Yh 


Number of pins in print-head 


num— labels 


nlab 


Nl 


Number of labels on screen (start at 1) 


output— res— char 


ore 


Yi 


Horizontal resolution in units per character 


output— res— line 


orl 


Vj 


Vertical resolution in units per line 


output— res— horz-inch 


orhi 


Yk 


Horizontal resolution in units per inch 


output— res— vert— inch 


orvi 


Yl 


Vertical resolution in units per inch 


padding— baud— rate 


pb 


pb 


Lowest baud rate where padding needed 


print-rate 


cps 


Ym 


Print rate in characters per second 


virtual— terminal 


vt 


vt 


Virtual terminal number (UNIX system) 


wide— char— size 


widcs 


Yn 


Character step size when in double wide mode 


width— status— line 


wsl 


ws 


Number of columns in status line 



Page# 

49 
24 
47 
47 
33 
32 
32 
24 
37 
30 

35 
42 
42 
35 

40 
40 
36 
47 
32 
39 
39 
39 
39 
34 



40 
34 
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Strings 



Variable 


Cap- 


Termcap 


Dedcription 


Page# 


name 


Code 






acs—chars 


acsc 


ac 


Graphic charset parts aAbBcC - det=vtlUU 


O't 


back_tab 


cbt 


bt 


Back tab 


11 
OO 


bell 


bel 


bl 


Audible signal (bell) 


25 


carriage—return 


cr 


cr 


Carriage return (♦) 


OR 


change_char_pitch 


cpi 


ZA 


Change number of characters per inch (dg 


4U 


change_line_pitch 


Ipi 


ZB 


Change number of lines per inch (dg 


41 


change_res_horz 


chr 


ZC 


Change horizontal resolution (dg 


41 


change_res_vert 


cvr 


ZD 


Change vertical resolution (dg 


4.1 


char\ge_scrolLjregion 


csr 


cs 


Change to lines #1 through #2 (vtlOO) (G) 


Zo 


char_padding 


rmp 


rP 


Like ip but when in replace mode 


oo 


char_set_naines 


csnm 


zy 


List of character set names 




clear_all_tabs 


tbc 


ct 


Clear all tab stops 


11 
OO 


clear—margins 


mgc 


MC 


Clear all margins (top, bottom, and sides) 


33 


dear— screen 


clear 


cl 


Clear screen and home cursor (*) 




clr— bol 


ell 


cb 


Clear to beginning of line, inclusive 




clr— eol 


el 


ce 


Clear to end of line 


27 


clr— eos 


ed 


cd 


Clear to end of display (*) 


zo 


column— address 


hpa 


ch 


Horizontal position absolute (G) 


27 


command— character 


cmdch 


CC 


Terminal settable cmd character in prototype 


37 


create— window 


cwin 


CW 


Define win #1 to go from #2,#3 to #4,#5 




cursor— address 


cup 


cm 


Move to row #1 col #2 (G) 


26 


cursor— down 


cudl 


do 


Down one line 


25 


cursor— home 


home 


ho 


Home cursor (if no cup) 




cursor— invisible 


civis 


vi 


Make cursor invisible 


Ox 


cursor— left 


cubl 


le 


Move left one space. 


25 


cursor— mem— address 


mrcup 


CM 


Memory relative cursor addressing (G) 


9A 
ZO 


cursor— normal 


cnorm 


ve 


Make cursor appear normal (undo vs/vi) 


1^ 

1 


cursor— right 


cufl 


nd 


Non-destructive space (cursor or carriage right) 


ZD 


cursor— tO— 11 


11 


11 


Last line, first column (if no cup) 


Z/ 


cursor— up 


cuul 


up 


Upline (cursor up) 


25 


cursor— visible 


cvvis 


vs 


Make cursor very visible 


if\ 
oV 


define— char 


defc 


ZE 


Define a character in a character setf 


46 


delete— character 


dchl 


dc 


Delete character (*) 


zy 


delete— line 


dU 


dl 


Delete line (*) 


28 


delete— phone 


dial 


DI 


Dial phone number #1 


34 


dis— status— line 


dsl 


ds 


Disable status line 


display— clock 


dclk 


DK 


Display time-of-day clock 




down— half—line 


hd 


hd 


Half-line down (forward 1/2 linefeed) 


37 


ena— acs 


enacs 


eA 


Enable alternate character set 


30 


enter— alt—charset— mode 


smacs 


as 


Start alternate character set 


30 


enter— am— mode 


smam 


SA 


Turn on automatic margins 




enter— blink— mode 


blink 


mb 


Turn on blinking 


30 


enter— bold—mode 


bold 


md 


Turn on bold (extra bright) mode 


30 


enter— ca_mode 


smcup 


ti 


String to begin programs that use cup 


31 


enter— delete— mode 


smdc 


dm 


Delete mode (enter) 


29 
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variaDie 


Cap- 
name 


Termcap 
Code 


Description 


Page# 


pntpr Him moHp 


dim 


mh 


Turn on half-bright mode 


30 


CIIIC1^UIJUI^1CVV1UC__IIIUUC 


swidm 


717 


Enable double wide printing 


45 


6nt6r_dr3ft_^u3lity 


sdrf(] 


ZaKJ 


Set draft quality print 


49 


pnfpt" incoT*t mo^o 


smir 


im 


Insert mode (enter) 


29 


enter — italics mode 


sitm 


ZH 


Enable italics 


45 


enter — leftward mode 


Sim 


ZI 


Enable leftward carriage motion 


43 


OTil'Ot" tY\i^Tt\ mf\/Aa 

ciiitfr — micru_nioae 


smicm 




Enable micro motion capabilities 


43 


OTifot* nosi* loffoi* /^itoli^ir 
ciiicr-_iicar__lciicr_v|Ualliy 


snl(] 




Set near-letter quality print 


49 


enter— normal — ^quality 


snrmq 


ZL 


Set normal quality print 


49 


enter — ^protected — mode 


prot 


mp 


Turn on protected mode 


30 


PTl^Of" fP\701*C0 TYl O 

Cl I i.cr__r c V crsc_iriuac 


rev 


mr 


Turn on reverse video mode 


30 


enter — secure mode 


in vis 


mk 


Turn on blank mode (characters invisible) 




enter — shadow mode 


sshm 


ZM 


Enable shadow printing 


45 


enter — standout mode 


smso 


so 


Begin standout mode 


30 


enter subscript—mode 


ssubm 


ZN 


Enable subscript printing 


45 


pnfpi* Cimorcr'rinf mrtAa 
Cl I ICl !*> U L/Cl 91.1 1 LI ' " lUUc 


ssupm 




Enable superscript printing 


45 


enter — ^underline mode 


smul 


US 


Start underscore mode 


30 


enter — upward mode 


sum 


•715 


Enable upward carriage motion 


43 


enter — xon mode 


smxon 


SX 


Turn on xon/xoff handshaking 


37 


erase ^chars 


ech 


ec 


Erase #1 characters (G) 


29 


gxit alt charset— mode 




ae 


End alternate character set 




exit— am— mode 


rmam 


RA 


Turn off automatic margins 




cAiL — diiiiuuic moQe 


sgrO 


me 


Turn off all attributes 


30 


cxii— Co— moue 


rmcup 


te 


String to end programs that use cup 


31 


exit delete_mode 


rmdc 


ed 


End delete mode 


29 


pvif HrtiiVt1piA7iHp mr\Ao 

CAA 1 \J.\J U L/IC W lUC— 11 ItJUC 


rwidm 




Disable double wide printing 


45 


exit — insert — mode 


rmir 


ei 


End insert mode 


29 


cAi 1 1 laiics — 11 luuc 


ntm 


7P 


Disable italics 


45 


pvif Ipftward mnHp 


rim 


7Q 


Enable rightward (normal) carriage motion 


43 


exit — micro mode 


rmicm 


ZT 


Disable micro motion capabilities 


43 


exit— shadow_mode 


rshm 


zu 


Disable shadow printing 


45 


exit — standout— mode 


rmso 


se 


End standout mode 


30 


exit — subscript mode 


rsubm 


zv 


Disable subscript printing 


45 


exit— superscript mode 


rsupm 


zw 


Disable superscript printing 


45 


exit ^underline— mode 


rmul 


ue 


End underscore mode 


30 


exit — upward mode 


rum 


Za 


Enable downward (normal) carriage motion 


43 


cxiL — xuri— mouc 


rmxon 


D V 

Ka 


Turn off xon/xoff handshaking 


37 


fixed — pause 


pause 


PA 


Pause for 2-3 seconds 




flash hook 


hook 


fh 


pidaii inc swiicn nooK 




flash—screen 


flash 


vb 


Visible bell (may not move cursor) 


30 


form— feed 


ff 


ff 


Hardcopy terminal page eject (*) 


33 


from— status— line 


fsl 


fs 


Return from status line 


34 


goto_window 


wingo 


WG 


Got to window #1 




hangup 


hup 


HU 


Hang-up phone 




init—1 string 


isl 


il 


Terminal or printer initialization string 


33 


init_2string 


is2 


is 


Terminal or printer initialization string 


33 


iniL_3string 


is3 


i3 


Terminal or printer initialization string 


33 
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TERMINFO(4) 



(Terminal Information Utilities) 



TERMINFO(4) 



Variable 


Cap- 


Termcap 


name 


Code 


init — file 


if 


if 


init ^prog 


iprog 


iP 


initialize — color 




Ic 


initialize — ^pair 


initp 


In 
^P 


insert—character 


icni 


ic 


insert-Jine 


ill 
Hi 


al 


insert—padding 




ip 


key_al 


Kai 


Kl 


key_a3 


KaO 




key_b2 


KDZ 




key—backspace 


KDS 


kb 


key— beg 


kbeg 


@1 


key_btab 


kcbt 


kB 


key_cl 


KCl 


K4 


key_c3 


KCO 




key— cancel 


kcan 




key_catab 


ktbc 


Ka 


key_clear 


Kcir 


KVw 


key_close 


kclo 




key_command 


kcmd 


@4 


key_copy 


kcpy 




key— create 


kcrt 


\a/o 


key_ctab 


kctab 


kt 


key_dc 


Kucni 


kD 


key— dl 


kdll 


kL 


key— down 




kd 


key_eic 


krmir 


kM 


key_end 


kend 


@7 


key_enter 




@8 


key_eol 


kel 


kE 


key_eos 


ked 


kS 


key— exit 


kext 


@9 


key— fO 


kfO 


kO 


key_fl 


kfl 


kl 


key_f2 


KIZ 


k2 


key_f3 


Ufa 


va 


key— f4 


Kr4 


VA 
K*l 


key_f5 


ki5 




key_f6 


KID 


k6 


key-f7 


kf7 


k7 


key-f8 


kf8 


kS 


key_f9 


kf9 


k9 


key-flO 


kflO 


k; 


key-fll 


kfll 


Fl 


key_fl2 


kfl2 


F2 


key_fl3 


kfl 3 


F3 


key_fl4 


kfl4 


F4 



Description 

Name of initialization file 

Path name of program for initialization 

Initialize the definition of color 

Initialize color-pair 

Insert character 

Add new blank line (*) 

Insert pad after character inserted (♦) 

KEY_A1, 0534, upper left of keypad 

KEY_A3, 0535, upper right of keypad 

KEY_B2, 0536, center of keypad 

KEY-BACKSPACE, 0407, sent by backspace key 

KEY-BEG, 0542, sent by beg(inning) key 

KEY-BTAB, 0541, sent by back-tab key 

KEY-Cl, 0537, lower left of keypad 

KEY_C3, 0540, lower right of keypad 
KEY-CANCEL, 0543, sent by cancel key 
KEY-CATAB, 0526, sent by clear-all-tabs key 
KEY_CLEAR, 0515, sent by clear-screen or erase key 
KEY-CLOSE, 0544, sent by close key 
KEY-COMMAND, 0545, sent by cmd (command) key 
KEY-COPY, 0546, sent by copy key 
KEY-CREATE, 0547, sent by create key 
KEY-CTAB, 0525, sent by clear-tab key 
KEY-DC, 0512, sent by delete-character key 
KEY-DL, 0510, sent by delete-line key 
KEY-DOWN, 0402, sent by terminal down-arrow key 
KEY—EIC, 0514, sent by rinir or smir in insert mode 
KEY-END, 0550, sent by end key 
KEY-ENTER, 0527, sent by enter/send key 
KEY_EOL, 0517, sent by clear-to-end-of-line key 
KEY-EOS, 0516, sent by clear-to-end-of-screen key 
KEY— EXIT, 0551, sent by exit key 
KEY-F(O), 0410, sent by function key fO 
KEY_F(1), 0411, sent by function key fl 
KEY_F(2), 0412, sent by function key f2 
KEY_F(3), 0413, sent by function key f3 
KEY-F(4), 0414, sent by function key f4 
KEY-F(5), 0415, sent by function key f5 
KEY_F(6), 0416, sent by function key f6 
KEY-F(7), 0417, sent by function key f7 
KEY-F(8), 0420, sent by function key f8 
KEY-F(9), 0421, sent by function key f9 
KEY_F(10), 0422, sent by function key flO 
KEY_F(11), 0423, sent by function key fll 
KEY_F(12), 0424, sent by function key fl2 
KEY-F(13), 0425, sent by function key fl3 
KEY_F(14), 0426, sent by function key fl4 



Page# 

25 
33 
35 
36 
29 
28 
29 
32 
32 
32 
32 



32 
32 



32 
32 



32 
32 
32 
32 
32 



32 
32 

32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
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TERMINFO(4) 



(Terminal Information Utilities) 



TERMINFO(4) 



Variable 


Cap- 


Termcap 




name 


Code 


key_fl5 


vn R 




J^gy 


V(1 A 
Kilo 


ro 


Key 1 1 / 


VC1 7 
Kll/ 


F7 


Van (1 fi 

Key — rio 


vet Q 
Kilo 


F8 


Key 117 


k£19 


F9 


Key izu 


k£20 


FA 


Key iz 1 


vot 
Kizl 


FB 


Vail fOO 

Key izz 


Kizz 


FC 


Key 


Kizj 


FD 


Key IZ4 


Kiz4 


FE 


Key — tZ3 


k£25 


FF 


Key izo 


k£26 


FG 


Key — IZ / 


k£27 


FH 


Key — izo 


k£28 


FI 


Key izy 


kf29 


FJ 


Uiair fan 
Key — i6\j 


k£30 


FK 


Key lo 1 


k£31 


FL 


Key i«3z 


kf32 


FM 


Key — Toa 


k£33 


FN 


Key I j*i 


VC1A 

Kij4 


FO 


Key lao 


voc 


FP 


Key — ijo 


KWo 


FQ 


key_f37 


veil 


rK 




KMo 


TC 

rb 


Key 1.57 


Kwy 


FT 


key _f40 


Ki4U 


FU 




VCA 1 

Ki41 


FV 


Key iftz 


Kt4z 


FW 


j^gy 


VCAO. 

Ki4o 


FX 


Key I't'x 


kf44 


FY 


Vmw cak. 
Key r4i) 


kf45 


FZ 


f/1Z 

Key t4o 


kf46 


Fa 


key £47 


kf47 


Fb 


key — f48 


k£48 


Fc 


Key r4y 


k£49 


Fd 


key_f50 


kfSO 


Fe 


key_f51 • 


kfSl 


Ff 


key £52 


kf52 


Fg 


j^ey £53 


KID J 


cu 
rn 


key_£54 


kf54 


Fi 


key_f55 


k£55 


Fj 


key_f56 


k£56 


Fk 


key_f57 


k£57 


Fl 


key_£58 


k£58 


Fm 


key_£59 


k£59 


Fn 


key_f60 


k£60 


Fo 


key_£61 


kf61 


Fp 



Description 

KEY_F(15), 0427, sent by £unction key £15 
KEY_F(16), 0430, sent by function key £16 
KEY_F(17), 0431, sent by function key £17 
KEY_F(18), 0432, sent by function key fl8 
KEY_F(19), 0433, sent by function key fl9 
KEY_F(20), 0434, sent by function key f20 
KEY_F(21), 0435, sent by function key f21 
KEY_F(22), 0436, sent by function key f22 
KEY_F(23), 0437, sent by function key f23 
KEY_F(24), 0440, sent by function key f24 
KEY_F(25), 0441, sent by function key f25 
KEY_F(26), 0442, sent by function key f26 
KEY_F(27), 0443, sent by function key f27 
KEY_F(28), 0444, sent by function key f28 
KEY_F(29), 0445, sent by function key f29 
KEY_F(30), 0446, sent by function key f30 
KEY_F(31), 0447, sent by function key f31 
KEY_F(32), 0450, sent by function key f32 
KEY_F(13), 0451, sent by function key fl3 
KEY_F(34), 0452, sent by function key f34 
KEY_F(35), 0453, sent by function key f35 
KEY_F(36), 0454, sent by function key f36 
KEY_F(37), 0455, sent by function key f37 
KEY_F(38), 0456, sent by function key f38 
KEY_F(39), 0457, sent by function key f39 
KEY_F(40), 0460, sent by function key f40 
KEY_F(41), 0461, sent by function key f41 
KEY__F(42), 0462, sent by function key f42 
KEY_F(43), 0463, sent by function key f43 
KEY_F(44), 0464, sent by function key f44 
KEY_F(45), 0465, sent by function key f45 
KEY__F(46), 0466, sent by function key f46 
KEY_F(47), 0467, sent by function key f47 
KEY_F(48), 0470, sent by function key f48 
KEY_F(49), 0471, sent by function key f49 
KEY_F(50), 0472, sent by function key f50 
KEY_F(51), 0473, sent by function key f51 
KEY_F(52), 0474, sent by function key f52 
KEY_F(53), 0475, sent by function key f53 
KEY_F(54), 0476, sent by function key f54 
KEY_F(55), 0477, sent by function key f55 
KEY_F(56), 0500, sent by function key f56 
KEY_F(57), 0501, sent by function key f57 
KEY_F(58), 0502, sent by function key f58 
KEY_F(59), 0503, sent by function key f59 
KEY_F(60), 0504, sent by function key f60 
KEY_F(61), 0505, sent by function key f61 



Page# 

32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 

32 . 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 

32 



-8- 



TERMINFO(4) 



(Terminal Information Utilities) 



TERMINFO(4) 



Variable 


Cap- 


Termcap 


name 


Code 


key_f62 


KiOZ 


hq 


key_f63 


KlOO 


rr 


key_find 


Kina 




key— help 


khlp 


0/ 1 

Vol 


key— home 


khome 


kh 


key— ic 


Kicni 


Kl 


key_il 


Kill 


K/\ 


key_Ieft 


KCUDl 


Kl 


key— 11 


Kll 


Kn 


key— mark 


KmrK 




key_message 


kmsg 




key— move 


kmov 


OLA 


key— next 


knxt 


0/ K 
70 D 


key_npage 


knp 


kN 


key— open 


kopn 


%6 


key_options 


kopt 


70/ 


key-ppage 


kpp 


Kl 


key— previous 


kprv 


%8 


key—print 


kprt 


0/ 

707 


key— redo 


krdo 


/0\J 


key—reference 


Kret 


J?r1 

OCi 


key— refresh 


Krir 




key— replace 


Krpi 


&3 


key— restart 


krst 




key— resume 


kres 


&5 


key— right 


KCUIJl 


kr 


key— save 


ksav 


&6 


key— sbeg 






key— scancel 


KV_A1N 




key_scommand 




*1 


key— scopy 


Kv_l I 


♦2 


key— screate 


KL-Kl 


^0 


key_sdc 


kDC 


*4 


key— sdl 


kDL 


*R 

*o 


key— select 


kslt 


*o 


key— send 


kEND 


♦7 


key_seol 


kEOL 


*8 


key—sexit 


kEXT 


♦9 


key— sf 


Kind 


Kr 


key_sfind 


kFND 


♦0 


key— shelp 


kHLP 


#1 


key— shome 


kHOM 


#2 


key— sic 


kIC 


#3 


key_sleft 


kLFT 


#4 


key_smessage 


kMSG 


%a 


key_smove 


kMOV 


%b 


key— snext 


kNXT 


%c 



Description 



Page# 



KEY_F(62), 0506, sent by function key f62 
KEY-F(63), 0507, sent by function key f63 
KEY-FIND, 0552, sent by find key 
KEY-HELP, 0553, sent by help key 
KEY-HOME, 0406, sent by home key 
KEY_IC, 0513, sent by ins-char/enter ins-mode key 
KEY— IL, 0511, sent by insert-line key 
KEY— LEFT, 0404, sent by terminal left-arrow key 
KEY_LL, 0533, sent by home-down key 
KEY-MARK, 0554, sent by mark key 
KEY-MESSAGE, 0555, sent by message key 
KEY-MOVE, 0556, sent by move key 
KEY-NEXT, 0557, sent by next-object key 
KEY-NPAGE, 0522, sent by next-page key 
KEY-OPEN, 0560, sent by open key 
KEY-OPTIONS, 0561, sent by options key 
KEY-PPAGE, 0523, sent by previous-page key 
KEY-PREVIOUS, 0562, sent by previous-object key 
KEY-PRINT, 0532, sent by print or copy key 
KEY-REDO, 0563, sent by redo key 
KEY-REFERENCE, 0564, sent by ref(erence) key 
KEY-REFRESH, 0565, sent by refresh key 
KEY-REPLACE, 0566, sent by replace key 
KEY-RESTART, 0567, sent by restart key 
KEY-RESUME, 0570, sent by resume key 
KEY-RIGHT, 0405, sent by terminal right-arrow key 
KEY-SAVE, 0571, sent by save key 
KEY-SBEG, 0572, sent by shifted beginning key 
KEY_SCANCEL, 0573, sent by shifted cancel key 
KEY-SCOMMAND, 0574, sent by shifted command key 
KEY_SCOPY, 0575, sent by shifted copy key 
KEY-SCREATE, 0576, sent by shifted create key 
KEY-SDC, 0577, sent by shifted delete-char key 
KEY-SDL, 0600, sent by shifted delete-line key 
KEY-SELECT, 0601, sent by select key 
KEY-SEND, 0602, sent by shifted end key 
KEY-SEOL, 0603, sent by shifted dear-line key 
KEY-SEXIT, 0604, sent by shifted exit key 
KEY-SF, 0520, sent by scroll-forward/down key 
KEY-SFIND, 0605, sent by shifted find key 
KEY-SHELP, 0606, sent by shifted help key 
KEY-SHOME, 0607, sent by shifted home key 
KEY_SIC, 0610, sent by shifted input key 
KEY-SLEFT, 0611, sent by shifted left-arrow key 
KEY_SMESSAGE, 0612, sent by shifted message key 
KEY-SMOVE, 0613, sent by shifted move key 
KEY-SNEXT, 0614, sent by shifted next key 



32 
32 
32 
32 
32 



32 



32 



32 



32 
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TERMINFO(4) 



(Terminal Information Utilities) 



TERMINFO(4) 



Variable 


Cap- 
name 


Termcap 
Code 


Description 


key_soptions 


kOPT 


%d 


KEY_SOPTIONS 061 S SPnt hv QhiftpH nr»rir»nc leav 


key__sprevious 


kPRV 


%e 


KEY_SPREVIOUS 0616 c:«>nf hv chifl-pH r»r*>v Voir 


key__sprint 


kPRT 


%f 


KEY_SPRINT 0617 «;pnt hv QhiffpH nrinf Wpv 


key_sr 


kri 


kR 


KEY *?R OS^l Qpnf hv crrnll-harlriA/ar/1 /hm V-o'.f 
1^*- * — CJIV/ belli Dy aCiOli-DaCKWarQ/Up KCy 


key_sredo 


kRDO 




KEY SREDO 0620 <5pnt hv QhiffpH rpHn tpv 


key_sreplace 


kRPL 


%h 


KEY SREPLACE 0651 QPnf hv chiftpH rpnla^o Vaxj 


key_sright 


kRIT 


%i 


rvii 1 — ijixivji 1 1 , uD^z, &eni Dy sniiieu ngnt-arrow Key 


key srsume 


kRES 


%i 

/OJ 


'xEi — ^i\^uivic, uOica/ seui oy sniiiea resume Key 


key_ssave 


kSAV 


!1 


KEY S^vAVF 0694 QPnf hv chiffpri cavo l-otr 

1 — jyjt\ V jc, uD^rt, bene uy sniiieu save Key 


key ssuspend 


kSPD 


12 


— ;7;:7u^i EiiNL/, uozo^ sent oy snitcea suspend Key 


key stab 


khts 


kT 


iNE I — ji/\D, sent Dy set-taD Key 


key sundo 


kUND 


!3 


I — ouiNL/w, uozO/ sent oy sniitea undo Key 


key__suspend 


kspd 


&7 


KEY SUSPEND 0^*97 CPnf hv cucnortH Xrcni 

'xiii_juji ciNL^, uoi^// Sent py suspend Key 


key_undo 


kund 


&8 


KFY UNDO OA^n cpnf hv iinr)r» l-otr 

ixE I — \jvHu\j, voovj, sent uy unuo Key 


kev— up 


kcuul 


ku 


*xii I — yjii, Kj'tvjf sent oy terminal up-arrow Key 


keypad local 


rmkx 


ke 


liilt of "l^Pvr»aH-H"ancmif " m/-\Aa 

\jui sji Jvcypau-iransnui mooe 


keypad xmit 


smkx 


ks 


I ui leiuuiidi 111 Keypau-transmit mode 


lab_fO 


IfO 


10 


T ahpic nn fiinr>firtn Votr (f\ i( ni-wf (f\ 

i-iaucio Kjii luiiciiun Key lu 11 not lu 


lab_fl 


Ifl 


11 


T ^hplc nn fiinr>Hr>n f1 i( r\nt- (1 
•-•ai'Cia iuiii.iiL/11 Key ix ii not 11 


lab_f2 


lf2 


12 


LxtPeis on lunction Key iz ir not tz, 


lab_f3 


lf3 


13 


■-•aucxs on lunction Key ij it not la 


lab_f4 


lf4 


14 


Labels on function key f4 if not f4 


lab_f5 


lf5 


15 


Lidueis on lunction Key id it not ID 


lab_f6 


lf6 


16 


T ahplQ on fnnrfion Wpv fA i( nof 
•-•tiL/cia uii iuiii.ii(Jll Key lO 11 ilOl lO 


lab_f7 


U7 


17 


Labels on fiinrrion Wpv f7 if nof f7 
*-»t«ftu iuii^ii\jii ^ey 1/ 11 iioi 1/ 


lab_f8 


lf8 


18 


T ahpl^ on fnnr^Hon Vpv (A if nof (fl 
L^aL/cia uii 1U11V.1101I Key lO 11 llOt lO 


lab_f9 


lf9 


19 


Labpl^ on fiinrHon Wpv fO if nrtf fQ 

•-'Mi-'eia \jii iuill.ll(jll Key ly 11 HOI II' 


lab_flO 


IflO 


la 


Labpl^ on fnnpHon Vpv fin if r»r»f fin 
•-""••'eio wii 1U1IV.L101I Key ixu 11 noi I xyj 


label—format 


fln 


Lf 


Label format 


labeLoff 


rmln 


LF 


Turn off soft labels 


label—on 


smln 


LO 


Turn on coff lahplc 


meta ^off 






1 um on meta mode 


meta on 


smm 




1 um on meta mode ^otn Dit^ 


micro_column_address 


mhpa 


ZY 


T.IkP column jlH/1rpae fr\r mif^m a<>1tiiol-*v«Aml-4> 

L^ir^e cuAuutiL_auurc99 lor micro aajustmentT 


micro_down 


mcudl 


ZZ 


LiiKc cuTsur — auwn lor micro adjustment 


micro—left 




Za 


Like cursor— left for micro adjustment 


11 11L.1 KJ 1 t^I 1 1 


mcuil 


Z.D 


Like cursor__right for micro adjustment 


micro row_address 




Zc 


Like row_address for micro adjustment "j" 


micro_up 


mcuul 


Zd 


Lii^e kui9ur__u.|^ loi micro aujustment 


newline 


nel 


nw 


Newline (behaves like cr followed by If) 


order_of_pins 


porder 


Ze 


Matches software bits to print-head pins 


orig_colors 


oc 


oc 


Set all color(-pair)s to the original ones 


orig_pair 


op 


op 


Set default color-pair to the original one 


pad_char 


pad 


pc 


Pad character (rather than null) 


parm_dch 


dch 


DC 


Delete #1 chars (G*) 


parm_delete_line 


dl 


DL 


Delete #1 lines (G*) 


parm_down_cursor 


cud 


DO 


Move down #l'lines. (G*) 



Page# 



32 



32 



32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 

32 
32 
37 
37 
42 
42 
42 
42 
42 
42 
25 
47 
36 
36 
36 
29 
28 
27 
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TERMINFO(4) 



Variable 


Cap- 


Termcap 


name 


Code 


pdinn down — micro 


mcud 


Zf 


paitn ich 


ich 


IC 


parm index 


indn 


SF 


panxi—insert line 


11 


AL 


parm left — cursor 




LE 


parm left — micro 


mcub 
ojf" 




parm right — cursor 




RI 


parm right — micro 


mcuf 


Zh 


parm rindex 


nn 


SR 


parm — ^up — cursor 




UP 


parm_up micro 


nicuu 


Zi 


pkey_key 


ptkey 


ok 
pK. 


pkey_local 






pkey_xmit 


piX 


px 


plab norm 




pn 


print — screen 


mcO 


ps 


prtr__non 


mc4^ 


oO 
P^ 


prtr_off 




nf 
P* 


prtr_on 


mc5 


po 


pulse 


pulse 


PU 


quick—dial 


qaiai 


or» 
K^U 


remove — clock 




RC 


repeat_char 


rep 


rp 


req_for_input 


rii 


RP 

R.r 


reset—lstring 


rsi 


ri 


reset_2string 


rsz 


rz 


reset_3string 


rsi 


Tj 


reset—file 


rf 


rf 


restore— cursor 


rc 




row— address 


vpa 




save_cursor 


sc 




scroll forward 


ind 


SI 


scroll—reverse 


n 




select— char—set 


scs 




set— attributes 


sgr 


sa 


set— background 


setb 


Sb 


set— bottom—margin 


smgb 


7V 


set— bottom— margin— parm 


I smgbp 


"71 

Zl 


set— clock 


SClK 




set— color— pair 


scp 


sp 


set—foreground 


setf 


Sf 


set-left— margin 


smgl 


ML 


set_left— margin— parm 


smglp 


Zm 


set-right— margin 


smgr 


MR 


set—right— margin— parm 


smgrp 


Zn 


set—tab 


hts 


st 


set—top— margin 


smgt 


Zo 



Description Page# 

Like parm_down— cursor for micro adjust. (G*) 42 
Insert #1 blank chars (G*) 

Scroll forward #1 lines. (G) 25 

Add #1 new blank lines (G*) 28 

Move cursor left #1 spaces (G) 27 

Like pann_left_cursor for micro adjust. ■\ 42 

Move right #1 spaces. (G*) 27 

Like parm_right_cursor for micro adjust, f 42 

Scroll backward #1 lines. (G) 25 

Move cursor up #1 lines. (G*) 27 

Like parm_up— cursor for micro adjust, -j- 42 



Prog funct key #1 to type string #2 
Prog funct key #1 to execute string #2 
Prog funct key #1 to xmit string #2 
Prog label #1 to show string #2 
Print contents of the screen 



Turn on the printer for #1 bytes 


37 


Turn off the printer 


37 


Turn on the printer 


37 


Select pulse dialing 




Dial phone number #1, without progress detection 




Remove time-of-day clock 




Repeat char #1 #2 times (G*) 


37 


Send next input char (for ptys) 


37 


Reset terminal completely to sane modes 


33 


Reset terminal completely to sane modes 


33 


Reset terminal completely to sane modes 


33 


Name of file containing reset string 


33 


Restore cursor to position of last sc 


28 


Vertical position absolute (G) 


27 


Save cursor position 


28 


Scroll text up 


25 


Scroll text down 


25 


Select character setf 


46 


Define the video attributes (G) #l-#9 


38 


Set current background color 


36 


Set bottom margin at current line 


44 


Set bottom margin at line #1 1 


44 


Set time-of-day clock 




Set current color-pair 


36 


Set current foreground colorl 


36 


Set left margin at current line 


33 


Set left margin at column #1 1 


44 


Set right margin at current column 


33 


Set right margin at column #1 1 


44 


Set a tab in all rows, current column 


33 


Set top margin at current line 


44 
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(Terminal Information Utilities) 



TERMINFO(4) 



Variable 



Cap- Temicap 
name Code 



Description 



Page# 



set tOD martrin narm 


smgtp 


zp 


Set top margin at line #1 1 


44 


S6t_window 


wind 


wi 


Current window is lines #l-#2 cols #3-#4 (G) 




start_bit_Jmage 


sbim 


Za 


Start printing bit image graphics 


47 


start_char set_def 




Zr 


Start definition of a character setf 


46 


stop bit image 


rbim 


Zs 


End printing bit image graphics 


47 


stop char set def 


rcsd 


Zt 


End definition of a character set 


46 


subscript characters 


subcs 


Zu 


List of "subscript-able" characters 


45 


superscript characters 




Zv 


List of "superscript-able" characters 


45 


tab 


ht 


ta 


Tab to next 8-space hardware tab stop 


33 


these ^cause cr 




Zw 


Printing any of these chars causes cr 


44 


to__status_line 


tsl 


ts 


Go to status line, col #1 (G) 


34 


tone 


tone 


TO 


Select touch tone dialing 




underline_char 


uc 




Underscore one char and move past it 




up half line 


nu 


nu 


Half-line up (reverse 1 /2 linefeed) 


37 


userO 


uu 


uu 


User string 




userl 


ul 


ul 


User string 1 




user2 


u2 


u2 


User string 4 




user3 


u3 


u3 


User string 3 




user4 


u4 


u4 


User string 4 




userS 


u5 


u5 


User string 5 




user6 


u6 


u6 


User string 6 




user7 


u7 


u7 


User string 7 




userS 


u8 


u8 


User string 8 




user9 


u9 


u9 


User string 9 




wait_tone 


wait 


WA 


Wait for dial tone 




xoff_character 


xoffc 


XF 


X-off character 


37 


xon_character 


xonc 


XN 


X-on character 


37 


zero_motion 


zerom 


Zx 


No motion for the subsequent character 


44 
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TERMINFO(4) 



(Teraiinal Information Utilities) 



TERMINFO(4) 



Booleans 



Cap- 


X/nriflhlA 
vaiiciuic 


Termcap 


Descrintion 1 


PagO' 


name 




Code 




auto right margin 


am 


Terminal has automatic margins 


25 


bw 


autQ Ipft margin 


bw 


cubl wraps from column to last column 


25 








Terminal can re-define existing color 


35 


chts 


hard_cursor 


HC 


Cursor is hard to see 


30 


cpix 


cpi changes_res 


YF 


Changing character pitch changes resolution 


40 


cps 


print_rate 


Ym 


Print rate in characters per second 




crxm 


cr_cancels__micro_modem 


YB 


Using cr turns off micro mode 


43 




crcat6_ window 


CW 


Define win #1 to go from #2,#3 to #4,#5 




da 


memory above 


da 


Display may be retained above the screen 


28 


daisy 


has print whppi 


YC 


Printer needs operator to change character set 


46 


dclk 


display clock 


DK 


Display time-of-day clock 




db 


memory below 


db 


Display may be retained below the screen 


28 


dial 


(Jia] ^phone 


DI 


Dial phone number #1 






oracp ovprcfrilfP 
dcidc_wvcrisiii^c 




Can erase overstrikes with a blank 


31 


eslok 


cfafiic linp Per* rtW 




Escape can be used on the status line 


34 


6" 


generic type 


en 

o 


Generic line type (e.g., dialup, switch) 


37 


he 


ViarH ronv 


he 


Hardcopy terminal 


25 


Vilc 

nis 


nUC llKlllIlC93^-9Cll.UICtLl(Jll 


hi 


Terminal uses only HLS color notation (Tektronix) 


36 


Vic 

ns 


hac ctal'iic lino 


hs 


Mas extra "status line" 


34 


hz 


tilclg glitch 


hz 


Hazeltine; can't print tilde (") 


38 




insert null ^glitch 


in 


Insert mode distinguishes nulls 


29 


km 


Via^ mpfa Icpv 


km 


Has a meta key (shift, sets parity bit) 


37 




Irti rViancTPQ rp^ 


YG 


Changing line pitch changes resolution 


41 


mc5i 


r\r¥r cilpnf 

Lfl ll_9llClll 


5i 


Printer won't echo on screen 


37 




mr>\/p incprf moHp 




Safe to move while in insert mode 


29 


msgr 


TY\n\ro cfanHrtiif moHp 
11 UJ V c 9 idi luu u 1 — 11 it^uc 




Safe to move in standout modes 


30 




no naH rhar 

1 IV/— L/d^ 1 V-1 Idl 


NP 


Pad character doesn't exist 


36 


nmnc 


non_rev_rmcup 


NR 


smcup does not reverse rmcup 


31 


nxon 


needs_xon_xoff 


nx 


Padding won't work, xon/xoff required 




OS 


over_strike 


OS 


Terminal overstrikes on hard-copy terminal 


25 


sam 


semi_auto_right__margin 


YE 


Printing in last column causes cr 


43 


ul 


transparent—underline 


ul 


Underline character overstrikes 


31 


xenl 


eat_newline_glitch 


xn 


Newline ignored after 80 columns (Concept) 


38 


xhp 


ceol— standout—glitch 


xs 


Standout not erased by overwriting (hp) 


38 


xhpa 


col— addr— glitch 


YA 


Only positive motion for hpa/mhpa caps 


42 


xon 


xon_xoff 


xo 


Terminal uses xon/xoff handshaking 


25 


xsb 


no_esc— ctlc 


xb 


Beehive (fl=escape, f2=ctrl C) 


38 


xt 


dest_tabs_magic— smso 


xt 


Destructive tabs, magic smso char (tl061) 


38 


xvpa 


row— addr_glitch 


YD 


Only positive motion for vpa/mvpa caps 


42 
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(Terminal Information Utilities) 



TERMINFO(4) 



Numbers 



Cap- 


Variable 


name 




bufsz 


buffer—capacity 


colors 


max_colors 


cols 


columns 


cps 


print_rate 


it 


init_tabs 


Ih 


label—height 


lines 


lines 


Im 


lines— of— memory 


Iw 


label—width 


maddr 


max__micro_address 


mcs 


micro_coL_size 


mjump 


max— micro— jump 


mis 


micro— line— size 


ncv 


no— color— video 


nlab 


num labels 


npins 


number— of— pins 


ore 


outpuL_res— char 


orhi 


output__res— hor2:_inch 


orl 


output_res_line 


orvi 


output_res_vert_inch 


pairs 


max_pairs 


pb 


padding_baud__rate 


spinh 


dot_horz_spacing 


spinv 


dot— vert_spacing 


vt 


virtual— terminal 


widcs 


wide— char— size 


wsl 


width_status_line 


xmc 


magic_cookie_glitch 



_ . Description Page# 

Code 

Ya Number of bytes buffered before printing 49 

Co Maximum number of colors on the screen 35 

CO Number of columns in a line 24 

Ym Average print rate in characters per second 49 

it Tabs initially every # spaces 33 

Ih Number of rows in each label 32 

li Number of lines on a screen or a page 24 

Im Lines of memory if > lines; means varies 37 

Iw Number of columns in each label 32 

Yd Maximum value in micro address 42 

Yf Character step size when in micro mode 40 

Ye Maximum value in pann .—micro 42 

Yg Line step size when in micro mode 40 

NC Video attributes that can't be used with colors 36 

Nl Number of labels on screen (start at 1) 32 

Yh Number of pins in print-head 47 

Yi Horizontal resolution in units per character 39 

Yk Horizontal resolution in units per inch 39 

Yj Vertical resolution in units per line 39 

Yl Vertical resolution in units per inch 39 

pa Maximum number of color-pairs on the screen 35 

pb Lowest baud rate where padding needed 34 

Yc Spacing of dots horizontally in dots per inch 47 

Yb Spacing of pins vertically in pins per inch 47 

vt Virtual terminal number (UNIX system) 

Yn Character step size when in double wide mode 40 

ws Number of columns in status line 34 

sg Number of blank characters left by smso or rmso 30 
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(Terminal Information Utilities) 



TERMINFO(4) 



Strings 




Cap- 


Variable 


Termcap 


name 




Code 


acsc 


acs_chars 


ac 


bel 


bell 


bl 


blink 


enter_blink_mode 


mb 


bold 


enter_bold_mode 


md 


cbt 


back_tab 


bt 


chr 


change__res_horz 


ZC 


civis 


cursor—invisible 


vi 


clear 


clear_screen 


cl 


cmdch 


command—character 


CC 


cnonn 


cursor—normal 


ve 


qpi 


change— char— pitch 


ZA 


cr 


carriage— return 


cr 


csnm 


char— set— names 


Zy 


csr 


change— scroll— region 


cs 


cub 


parm_left_cursor 


LE 


cubl 


cursor—left 


le 


cud 


parm_down_cursor 


DO 


cuf 


parm_right_cursor 


RI 


cufl 


cursor— right 


nd 


cup 


cursor_address 




cuu 


parm_up_cursor 


UP 


cvr 


change— res— vert 


ZD 


cvvis 


cursor— visible 


vs 


dch 


parm— dch 


DC 


dchl 


delete— character 


dc 


defc 


define— char 


ZE 


dim 


enter— dim_mode 


mh 


dl 


delete_line 


dll 


dl 


parm— delete— line 


DL 


do 


cursor— down 


do 


doer 


these— cause— cr 


Zw 


dsl 


dis— status— line 


ds 


ech 


erase— chars 




ed 


clr_eos 


cd 


el 


clr— eol 




ell 


clr-bol 


cb 


enacs 


ena acs 


eA 


ff 


form— feed 


ff 


flash 


flash—screen 


vb 


fln 


label— format 


Lf 


fsl 


from— status— line 


fs 


hd 


down— half— line 


hd 


home 


cursor— home 


ho 


hook 


flash— hook 


fli 


hpa 


column— address 


ch 



Description Page# 

Graphic charset pairs aAbBcC - def=vtlOO 34 

Audible signal (bell) 25 

Turn on blinking 30 

Turn on bold (extra bright) mode 30 

Back tab 33 

Change horizontal resolution -j- 41 

Make cursor invisible 31 

Clear screen and home cursor (*) 24 

Terminal settable cmd character in prototype 37 

Make cursor appear normal (undo vs/vi) 31 

Change number of characters per inch -f 40 

Carriage return (*) 25 

List of character set names 46 

Change to lines #1 through #2 (vtlOO) (G) 28 

Move cursor left #1 spaces (G) 27 

Move left one space. 25 

Move down #1 lines. (G*) 27 

Move right #1 spaces. (G*) 27 

Non-destructive space (cursor or carriage right) 25 

Move to row #1 col #2 (G) 26 

Move cursor up #1 lines. (G*) 27 

Change vertical resolution! 41 

Make cursor very visible 30 

Delete #1 chars (G*) 29 

Delete character (*) 29 

Define a character in a character set 46 

Turn on half-bright mode 30 

Delete line (*) 28 

Delete #1 lines (G*) 28 

Down one line 25 

Printing any of these chars causes cr 44 

Disable status line 34 

Erase #1 characters (G) 29 

Clear to end of display (♦) 28 

Clear to end of line 27 

Clear to beginning of line, inclusive 24 

Enable alternate character set 30 

Hardcopy terminal page eject (*) 33 

Visible bell (may not move cursor) 30 
Label format 

Return from status line 34 

Half-line down (forward 1/2 linefeed) 37 

Home cursor (if no cup) 27 
Flash the switch hook 

Horizontal position absolute (G) 27 
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Variable 


Termcap 


Description 


Page# 


name 




Code 






ht 


tab 


ta 


Tab to next 8-space hardware tab stop 


33 


hts 


set-tab 


St 


Set a tab in all rows, current column 


33 


hu 


up_half_line 


hu 


Half-line up (reverse 1 /2 linefeed) 


37 


hup 


hangup 


HU 


Hang-up phone 




ich 


parm_ich 


IC 


Insert #1 blank chars (G*) 




ichl 


insert—character 


ic 


Insert character 


29 


if 


init_file 


if 


Name of initialization file 


25 


il 


parm— insert— line 


AL 


Add #1 new blank lines (G*) 


28 


ill 


insert—line 


al 


Add new blank line (*) 


28 


ind 


scroll— forward 


sf 


Scroll text up 


25 


indn 


parm_index 


SF 


Scroll forward #1 lines. (G) 


25 


initc 


initialize— color 


Ic 


Initialize the definition of color 


35 


initp 


initialize—pair 


IP 


Initialize color-pair 


36 


invis 


enter— secure_mode 


mk 


Turn on blank mode (characters invisible) 




ip 


insert—padding 


ip 


Insert pad after character inserted (*) 


29 


iprog 


init— prog 


iP 


Path name of program for initialization 


33 


isl 


init—1 string 


il 


Terminal or printer initialization string 


33 


is2 


init_2string 


is 


Terminal or printer initialization string 


33 


is3 


init_3string 


13 


Terminal or printer initialization string 


33 


kBEG 


key_sbeg 


&9 


KEY_SBEG, 0572, sent by shifted beginning key 




kCAN 


key— scancel 


&0 


KEY_SCANCEU 0573, sent by shifted cancel key 




kCMD 


key— scommand 


♦1 


KEY-SCOMMAND, 0574, sent by shifted command key 




kCPY 


key— scopy 


♦2 


KEY-SCOPY, 0575, sent by shifted copy key 




kCRT 


key— screate 


♦3 


KEY-SCREATE, 0576, sent by shifted create key 




kDC 


key— sdc 


♦4 


KEY_SDC, 0577, sent by shifted delete-char key 




kDL 


key— sdl 


*5 


KEY-SDL, 0600, sent by shifted delete-line key 




kEND 


key_send 


♦7 


KEY-SEND, 0602, sent by shifted end key 




kEOL 


key— seol 


♦8 


KEY-SEOL, 0603, sent by shifted clear-line key 




kEXT 


key_sexit 


♦9 


KEY_SEXIT, 0604, sent by shifted exit key 




kFND 


key— sfind 


♦0 


KEY_SFIND, 0605, sent by shifted find key 




kHLP 


key— shelp 


#1 


KEY_SHELP, 0606, sent by shifted help key 




kHOM 


key— shome 


#2 


KEY-SHOME, 0607, sent by shifted home key 




kIC 


key_sic 


#3 


KEY_SIC, 0610, sent by shifted input key 




kLFT 


key— sleft 


#4 


KEY-SLEFT, 0611, sent by shifted left-arrow key 




kMOV 


key— smove 


%b 


KEY-SMOVE, 0613, sent by shifted move key 




kMSG 


key— smessage 


%a 


KEY-SMESSAGE, 0612, sent by shifted message key 




kNXT 


key— snext 


%c 


KEY-SNEXT, 0614, sent by shifted next key 




kOPT 


key— soptions 


%d 


KEY— SOPTIONS, 0615, sent by shifted options key 




kPRT 


key_sprint 


%f 


KEY-SPRINT, 0617, sent by shifted print key 




kPRV 


key_sprevious 


%e 


KEY-SPREVIOUS, 0616, sent by shifted prev key 




kRDO 


key_sredo 


%g 


KEY-SREDO, 0620, sent by shifted redo key 




kRES 


key— srsume 


%j 


KEY_SRSUME, 0623, sent by shifted resume key 




kRIT 


key— sright 


%i 


KEY-SRIGHT, 0622, sent by shifted right-arrow key 




kRPL 


key— sreplace 


%h 


KEY_SREPLACE, 0621, sent by shifted replace key 




kSAV 


key— ssave 


!1 


KEY-SSAVE, 0624, sent by shifted save key 




kSPD 


key— ssuspend 


!2 


KEY-SSUSPEND, 0625, sent by shifted suspend key 




kUND 


key— sundo 


!3 


KEY-SUNDO, 0626, sent by shifted undo key 
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Csp' 


Variable 


Terincap 


Description 


Page# 


nsnuG 




Code 






kal 


key_al 


Kl 


KEY-Al, 0534, upper left of keypad 


32 


ka3 


key_a3 


K3 


KEY_A3, 0535, upper right of keypad 


32 


kb2 


key_b2 


K2 


KEY-B2, 0536, center of keypad 


32 


kbeg 


key_beg 


@1 


KEY_BEG, 0542, sent by beg(inning) key 




kbs 


key—backspace 


kb 


KEY— BACKSPACE, 0407, sent by backspace key 


32 


kcl 


key_cl 


K4 


KEY_C1, 0537, lower left of keypad 


32 


kc3 


key_c3 


K5 


KEY-C3, 0540, lower right of keypad 


32 


kcan 


key_cancel 


@2 


KEY-CANCEL, 0543, sent by cancel key 




kcbt 


key_btab 


kB 


KEY_BTAB, 0541, sent by back-tab key 




kclo 


key_close 


@3 


KEY—CLOSE, 0544, sent by close key 




kclr 


key_clear 


kC 


KEY—CLEAR, 0515, sent by clear-screen or erase key 


32 


kcmd 


key_command 


@4 


KEY-COMMAND, 0545, sent by cmd (command) key 




kcpy 


key_copy 


@5 


KEY-COPY, 0546, sent by copy key 




kcrt 


key_create 


@6 


KEY-CREATE, 0547, sent by create key 




kctab 


key_ctab 


kt 


KEY-CTAB, 0525, sent by dear-tab key 


32 


kcubl 


key_left 


kl 


KEY-LEFT, 0404, sent by terminal left-arrow key 


32 


kcudl 


key_down 


kd 


KEY— DOWN, 0402, sent by terminal down-arrow key 


32 


kcufl 


key—right 


kr 


KEY-RIGHT, 0405, sent by terminal right-arrow key 


32 


kcuul 


key_up 


ku 


KEY— UP, 0403, sent by terminal up-arrow key 


32 


kdchl 


key— dc 


kD 


KEY-DC, 0512, sent by delete-character key 


32 


kdll 


key— dl 


kL 


KEY-DL, 0510, sent by delete-line key 


32 


ked 


key— eos 


ked 


KEY-EOS, 0516, sent by dear-to-end-of-screen key 


32 


kel 


key— eol 


kE 


KEY-EOL, 0517, sent by clear-to-end-of-line key 


32 


kend 


key— end 


@7 


KEY—END, 0550, sent by end kee 




kent 


key— enter 


@8 


KEY-ENTER, 0527, sent by enter/send key 




kext 


key_exit 


@9 


KEY-EXIT, 0551, sent by exit key 




kfO 


key-fO 


kO 


KEY— F(0), 0410, sent by function key fO 


32 


kfl 


key-fl 


kl 


KEY— F(l), 0411, sent by function key fl 


32 


kflO 


key-flO 


k; 


KEY-F(IO), 0422, sent by function key flO 


32 


kfll 


key-fl 1 


Fl 


KEY— F(ll), 0423, sent by function key fll 


32 


kfl2 


key-fl2 


F2 


KEY-F(12), 0424, sent by function key fl2 


32 


kfl3 


key_fl3 


F3 


KEY_F(13), 0425, sent by function key fl3 


32 


kfl4 


key-fl4 


F4 


KEY-F(14), 0426, sent by function key fl4 


32 


kfl5 


key-fl5 


F5 


KEY-F(15), 0427, sent by function key fl5 


32 


kfl6 


key-fl6 


F6 


KEY_F(16), 0430, sent by function key fl6 


32 


kfl 7 


key-fl 7 


F7 


KEY_F(17), 0431, sent by function key fl7 


32 


kfl 8 


key-fl 8 


F8 


KEY-F(18), 0432, sent by function key fl8 


32 


kfl9 


key_fl9 


F9 


KEY-F(19), 0433, sent by function key fl9 


32 


kf2 


key_f2 


k2 


KEY— F(2), 0412, sent by function key f2 


32 


kf20 


key-f20 


FA 


KEY-F(20), 0434, sent by funcrion key f20 


32 


kf21 


key_f21 


FB 


KEY-F(21), 0435, sent by function key f21 


32 


kf22 


key-f22 


FC 


KEY_F(22), 0436, sent by function key f22 


32 


kf23 


key_f23 


FD 


KEY_F(23), 0437, sent by function key f23 


32 


kf24 


key-f24 


FE 


KEY-F(24), 0440, sent by function key f24 


32 


kf25 


key_f25 


FF 


KEY_F(25), 0441, sent by function key f25 


32 


kf26 


key_f26 


FG 


KEY_F(26), 0442, sent by function key f26 


32 


kf27 


key-f27 


FH 


KEY-F(27), 0443, sent by function key f27 


32 
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Cap- 


variaDie 


Termcap 


name 




Code 


kf28 


key_f28 


FI 


kf29 


key_f29 


FT 


kf3 


key_f3 


k3 


kf30 


j^gy 


FK 


kf31 


l^gy 


FL 


kf32 


key_f32 


FM 




Key — 


■pM 
riN 


kf34 


Key r«5ft 


PO 
r\J 




Key 


T7P 
rl 


Kr>50 


Key lao 






h-atr CXI 

Key I o / 


rK 




Key loo 




kf39 


key_f39 


FT 


kf4 


key f4 


Kfl 


kf40 


Voir fAn 

Key iftu 


rU 


kf41 


Key — i*t 1 


F\7 
r V 


kf42 


j^gy 


FW 
r vv 




Van (A'X 

Key I'ij 


rA 


kf44 


ke y f4 4 


FY 


kf45 


J^gy £45 


FZ 


kf46 


j^gy £45 


Fa 

ra 


kf47 


key_f47 


Fb 


kf48 


J^gy £4g 


Fc 


kf49 


key __f49 


Fd 


kf5 


key__f5 


k5 


kfSO 


key_f50 


Fe 


kfSl 


key_f51 


Ff 


kf52 


key_f52 


Fcr 


kf53 


Key — lOo 


FVi 


kf54 


j^gy £54 


Fi 

rl 




Key iDD 




KtDO 


Key — TDo 


rK 


KID/ 


Key 10 / 


CI 

rl 


KliJo 


key — iDo 


Fm 




Key toy 


Fn 


KIO 


key f6 


k6 


KroU 


Key roU 


Fo 


kf61 


key__f61 


Fp 


KIOZ 


key f62 


Fq 


kf63 


key_i63 


Fr 


kf7 


key_f7 


k7 


kf8 


key_f8 


k8 


kf9 


key_f9 


k9 


kfnd 


key_find 


@0 


khlp 


key_help 


%1 


khome 


key_home 


kh 


khts 


key_stab 


kT 



Description 

KEY_F(28), 0444, sent by function key £28 
KEY_F(29), 0445, sent by function key £29 
KEY_F(3), 0413, sent by function key f3 
KEY_F(30), 0446, sent by function key £30 
KEY_F(31), 0447, sent by function key f31 
KEY_F(32), 0450, sent by function key f32 
KEY_F(13), 0451, sent by function key fl3 
KEY_F(34), 0452, sent by function key f34 
KEY_F(35), 0453, sent by function key f35 
KEY_F(36), 0454, sent by function key f36 
KEY_F(37), 0455, sent by function key f37 
KEY_F(38), 0456, sent by function key f38 
KEY_F(39), 0457, sent by function key f39 
KEY_F(4), 0414, sent by function key f4 
KEY_F(40), 0460, sent by function key f40 
KEY_F(41), 0461, sent by function key f41 
KEY_F(42), 0462, sent by function key f42 
KEY_F(43), 0463, sent by function key f43 
KEY_F(44), 0464, sent by function key f44 
KEY_F(45), 0465, sent by function key f45 
KEY_F(46), 0466, sent by function key f46 
KEY__F(47), 0467, sent by function key f47 
KEY_F(48), 0470, sent by function key f48 
KEY_F(49), 0471, sent by function key f49 
KEY_F(5), 0415, sent by function key f5 
KEY_F(50), 0472, sent by function key f50 
KEY_F(51), 0473, sent by function key f51 
KEY_F(52), 0474, sent by function key f52 
KEY_F(53), 0475, sent by function key f53 
KEY_F(54), 0476, sent by function key f54 
KEY_F(55), 0477, sent by function key f55 
KEY_F(56), 0500, sent by function key f56 
KEY_F(57), 0501, sent by function key f57 
KEY_F(58), 0502, sent by function key f58 
KEY_F(59), 0503, sent by function key f59 
KEY_F(6), 0416, sent by function key f6 
KEY_F(60), 0504, sent by function key f60 
KEY_F(61), 0505, sent by function key f61 
KEY_F(62), 0506, sent by function key f62 
KEY_F(63), 0507, sent by function key f63 
KEY_F(7), 0417, sent by function key f7 
KEY_F(8), 0420, sent by function key f8 
KEY_F(9), 0421, sent by function key f9 
KEY_FIND, 0552, sent by find key 
KEY_HELP, 0553, sent by help key 
KEY_HOME, 0406, sent by home key 
KEY_STAB, 0524, sent by set-tab key 



Page# 

32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 
32 



32 
32 
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CaD- 


Variable 


Termcap 


Description 


Page# 


name 




Code 






kichl 


key_ic 


kl 


KEY— IC, 0513, sent by ins-char/enter ins-mode key 


32 


kill 


key_il 


kA 


KEY_IU 0511, sent by insert-line key 


32 


kind 


key_sf 


kF 


KEY— SF, 0520, sent by scroll-forward/down key 


32 


kll 


key-Jl 


kH 


KEY— LL, 0533, sent by home-down key 


32 


kmov 


key— move 


%4 


KEY—MOVE, 0556, sent by move key 




kmrk 


key_mark 


%2 


KEY— MARK, 0554, sent by mark key 




kmsg 


key— message 


%3 


KEY-MESSAGE, 0555, sent by message key 




knp 


key_npage 


kN 


KEY— NP AGE, 0522, sent by next-page key 


32 


knxt 


key— next 


%5 


KEY-NEXT, 0557, sent by next-object key 




kopn 


key— open 


%6 


KEY— OPEN, 0560, sent by open key 




kopt 


key— options 


%7 


KEY-OPTIONS, 0561, sent by options key 




kpp 


key— ppage 


kP 


KEY— PPAGE, 0523, sent by previous-page key 


32 


kprt 


key— print 


%9 


KEY—PRINT, 0532, sent by print or copy key 




kprv 


key—previous 


%8 


KEY— PREVIOUS, 0562, sent by previous-object key 




krdo 


key— redo 


%0 


KEY— REDO, 0563, sent by redo key 




kref 


key—reference 


&1 


KEY— REFERENCE, 0564, sent by ref(erence) key 




kres 


key— resume 


&5 


KEY-RESUME, 0570, sent by resume key 




krfr 


key— refresh 


&2 


KEY-REFRESH, 0565, sent by refresh key 




kri 


key— sr 


kR 


KEY— SR, 0521, sent by scroll-backward/up key 


32 


krmir 


key— eic 


kM 


KEY— EIC, 0514, sent by rmir or smir in insert mode 


32 


krpl 


key— replace 


&3 


KEY-REPLACE, 0566, sent by replace key 




krst 


key— restart 


&4 


KEY-RESTART, 0567, sent by restart key 




ksav 


key— save 


&6 


KEY-SAVE, 0571, sent by save key 




kslt 


key— select 


♦6 


KEY-SELECT, 0601, sent by select key 




kspd 


key—Suspend 


&7 


KEY-SUSPEND, 0627, sent by suspend key 




ktbc 


key— catab 


ka 


KEY-CATAB, 0526, sent by clear-all-tabs key 


32 


kund 


key— undo 


&8 


KEY-UNDO, 0630, sent by undo key 




IfO 


lab-fO 


10 


Labels on function key fO if not fO 


32 


in 


lab-fl 


11 


Labels on function key fl if not fl 


32 


IflO 


lab-flO 


la 


Labels on function key flO if not flO 


32 


lf2 


lab-f2 


12 


Labels on function key f2 if not f2 


32 


lf3 


lab_f3 


13 


Labels on function key f3 if not f3 


oL 


lf4 


lab_f4 


14 


Labels on function key f4 if not f4 


32 


lf5 


lab-f5 


15 


Labels on function key f5 if not f5 


32 


lf6 


lab_f6 


16 


Labels on function key f6 if not f6 


32 


lf7 


lab_f7 


17 


Labels on function key f7 if not f7 


32 


lf8 


lab-f8 


18 


Labels on function key f8 if not f8 


32 


lf9 


lab-f9 


19 


Labels on function key f9 if not f9 


32 


11 


cursor— to_ll 


11 


Last line, first column (if no cup) 


17 


Ipi 


change— line_pitch 


ZB 


Change number of lines per inch f 


41 


ma 


max— attributes 


ma 


Maximum combined video attributes terminal can display 


mcO 


print-screen 


ps 


Print contents of the screen 


37 


mc4 


prtr— off 


Pf 


Turn off the printer 


37 


mc5 


prtr— on 


po 


Turn on the printer 


37 


mc5p 


prtr— non 


pO 


Turn on the printer for #1 bytes 


37 


mcub 


parm_left— micro 


Zg 


Like parm_left— cursor for micro adjust, -f 


42 


mcubl 


micro— left 


Za 


Like cursor— left for micro adjustment 


42 
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Csp- 


Variable 


TeniK 




Code 


mcud 


parm_down_micro 


Zf 


mcudl 


micro_down 


zz 


mcuf 


parm_right_micro 


Zh 


mcufl 


micro—right 


Zb 


mcuu 


parm_up_micro 


Zi 


mcuul 


micro_up 


Zd 


mgc 


clear_inargins 


MC 


mhpa 


micro_column__address 


ZY 


mrcup 


cursor_mem_address 


CM 


mvpa 


micro_row_address 


Zc 


ndscr 


non_desL_scroll_region 


ND 


nel 


newline 


nw 


oc 


orig_colors 


oc 


op 


orig_pair 


op 


pad 


pad_char 


pc 


pause 


fixed—pause 


PA 


pfkey 


pkey_key 


pk 


pfloc 


pkey_local 


Pl 


pfx 


pkey—xmit 


px 


pin 


plab__norm 


pn 


porder 


order_oL_pins 


Ze 


prot 


enter_protected_mode 


mp 


pulse 


pulse 


PU 


qdial 


quick—dial 


QD 


rbim 


stop_bit_image 


Zs 


rc 


restore—cursor 


rc 


rcsd 


stop— char_set— def 


Zt 


rep 


repeat— char 


rp 


rev 


enter— reverse— mode 


mr 


rf 


reset— file 


rf 


rfi 


req— for— input 


RF 


ri 


scroll— reverse 


sr 


rin 


parm_rindex 


SR 


ritm 


exit_italics_mode 


ZR 


rim 


exit— leftward— mode 


ZS 


rmacs 


exit— alt— charset_mode 


ae 


rmam 


exit— am— mode 


RA 


rmclk 


remove— clock 


RC 


rmcup 


exit— ca— mode 


te 


rmdc 


exit— delete— mode 


ed 


nnicm 


exit_micro_mode 


ZT 


rmir 


exit_insert_mode 


ei 


rmkx 


keypad—local 


ke 


rmln 


labeLoff 


LF 


rmm 


meta—off 


mo 


rmp 


char— padding 


rP 


rmso 


exit— standout— mode 


se 



Description Page# 

Like parm_down_cursor for micro adjust. (G*) 42 

Like cursor— down for micro adjustment 42 

Like parm_right_cursor for micro adjust, f 42 

Like cursor— right for micro adjustment 42 

Like pami—up— cursor for micro adjust, f 42 

Like cursor— up for micro adjustment 42 

Clear all margins (top, bottom, and sides) 33 

Like column— address for micro adjustment f 42 

Memory relative cursor addressing (G) 26 

Like row— address for micro adjustment 42 
Scrolling region is non-destructive 

Newline (behaves like cr followed by If) 25 

Set all color(-pair)s to the original ones 36 

Set default color-pair to the original one 36 

Pad character (rather than null) 36 
Pause for 2-3 seconds 

Prog funct key #1 to type string #2 32 

Prog funct key #1 to execute string #2 32 

Prog funct key #1 to xmit string #2 32 

Prog label #1 to show string #2 32 

Matches software bits to print-head pins 47 

Turn on protected mode 30 
Select pulse dialing 

Dial phone number #1, without progress detection 

End printing bit image graphics 47 

Restore cursor to position of last sc 28 

End definition of a character set 46 

Repeat char #1 #2 times (G*) 37 

Turn on reverse video mode 30 

Name of file containing reset string 33 

Send next input char (for ptys) 37 

Scroll text down 25 

Scroll backward #1 lines. (G) 25 

Disable italics 45 

Enable rightward (normal) carriage motion 43 
End alternate character set 
Turn off automatic margins 
Remove time-of-day clock 

String to end programs that use cup 31 

End delete mode 29 

Disable micro motion capabilities 43 

End insert mode 29 

Out of "keypad-transmit" modey 32 

Turn off soft labels 32 

Turn off "meta mode" 37 

Like ip but when in replace mode 29 

End standout mode 30 
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Cap- 


Variable 


Termcap 


name 


Code 


rmul 


exit_underline_mode 


ue 


nnxon 


exit_xon_mode 


RX 


rsl 


reset 1 string 


TL 


rs2 


reset_2string 


r2 


rs3 


reset_3string 


r3 


rshm 


exit_shadow_mode 


ZU 


rsubm 


exit__subscript_mode 


zv 


rsupm 


exit_superscript_mode 


zw 


rum 


exit_upward_mode 


zx 


rwidm 


exit_doublewide_mode 


ZQ 


sbim 


start_bit_image 


Zq 


sc 


save_cursor 


sc 


sclk 


set_clock 


SC 


scp 


set_color_pair 


sp 


scs 


select_char_set 


Zj 


scsd 


start_char__set_def 


Zr 


sdrfq 


enter_draft_quality 


ZG 


setb 


set—background 


Sb 


setf 


set—foreground 


Sf 


sgr 


set—attributes 


sa 


sgrO 


exit_attribute— mode 


me 


sitm 


enter— italics— mode 


ZH 


slm 


enter— leftward— mode 


ZI 


smacs 


enter— alt— charset— mode 


as 


smam 


enter— am— mode 


SA 


smcup 


enter— ca— mode 


ti 


smdc 


enter— delete— mode 


dm 


smgb 


set— bottom— margin 


Zk 


smgbp 


set— bottom— margin— pamZl 


smgl 


set— left— margin 


ML 


smglp 


set— left— margiiL-parm 


Zm 


smgr 


set— right— margin 


MR 


smgrp 


set— right— margin— parm 


Zn 


smgt 


set— top— margin 


Zo 


smgtp 


set— top— margin— parm 


Zp 


smicm 


enter— micro_mode 


ZJ 


smir 


enter— insert—mode 


im 


smkx 


keypad— xmit 


ks 


smln 


label— on 


LO 


smm 


meta— on 


mm 


smso 


enter— standout— mode 


so 


smul 


enter— underline— mode 


us 


smxon 


enter— xon— mode 


SX 


snlq 


enter— near_letter—qualityZK 


snnnq 


enter— normal— quality 


ZL 


sshm 


enter— shadow— mode 


ZM 


ssubm 


enter— subscriptL_mode 


ZN 



Description 

End underscore mode 

Turn off xon/xoff handshaking 

Reset terminal completely to sane modes 

Reset terminal completely to sane modes 

Reset terminal completely to sane modes 

Disable shadow printing 

Disable subscript printing 

Disable superscript printing 

Enable downward (normal) carriage motion 

Disable double wide printing 

Start printing bit image graphics! 

Save cursor position 

Set time-of-day clock 

Set current color-pair 

Select character set| 

Start definition of a character setf 

Set draft quality print 

Set current background color 

Set current foreground color 

Define the video attributes #l-#9 (G) 

Turn off all attributes 

Enable italics 

Enable leftward carriage motion 

Start alternate character set 

Turn on automatic margins 

String to begin programs that use cup 

Delete mode (enter) 

Set bottom margin at current line 

Set bottom margin at line #1 1 

Set left margin at current line 

Set left margin at column #1 f 

Set right margin at current column 

Set right margin at column #1 -f 

Set top margin at current line 

Set top margin at line #1 f 

Enable micro motion capabilities 

Insert mode (enter) 

Put terminal in "keypad-transmit" mode 

Turn on soft labels 

Turn on meta mode " (8th bit) 

Begin standout mode 

Start underscore mode 

Turn on xon/xoff handshaking 

Set near-letter quality print 

Set normal quality print 

Enable shadow printing 

Enable subscript printing 



Page# 

30 
37 
33 
33 
33 
45 
45 
45 
43 
45 
47 
28 

36 
46 
46 
49 
36 
36 
38 
30 
45 
43 
30 

31 
29 
44 
44 
33 
44 
33 
44 
44 
44 
43 
29 
32 
32 
37 
30 
30 
37 
49 
49 
45 
45 
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Variable ^ . Description Page# 

name Code 



ssupm 


enter_superscript_mode 


ZO 


Enable superscript printing 


45 


subcs 


subscript—characters 


Zu 


List of "subscript-able" characters 


45 


sum 


enter_upward_n\ode 


ZP 


Enable upward carriage motion 


43 


supcs 


superscript—characters 


Zv 


List of "superscript-able" characters 


45 


swidm 


enter— doublewide— mode ZF 


Enable double wide printing 


45 


tbc 


clear— all— tabs 


ct 


Clear all tab stops 


33 


tone 


tone 


TO 


Select touch tone dialing 




tsl 


to_status_line 


ts 


Go to status line, col #1 (G) 


34 


uO 


userO 


uO 


User string 




ul 


userl 


ul 


User string 1 




u2 


user2 


u2 


User string 2 




u3 


user3 


u3 


User string 3 




u4 


user4 


u4 


User string 4 




u5 


userS 


u5 


User string 5 




u6 


user6 


u6 


User string 6 




u7 


user7 


u7 


User string 7 




u8 


userS 


u8 


User string 8 




u9 


user9 


u9 


User string 9 




uc 


underline— char 


uc 


Underscore one char and move past it 




up 


cursor_up 


cuul 


Upline (cursor up) 


25 


vpa 


row_address 


cv 


Vertical position absolute (G) 


27 


wait 


wait— tone 


WA 


Wait for dial tone 




wind 


set— window 


wi 


Current window is lines #l-#2 cols #3-#4 (G) 




wingo 


goto— window 


WG 


Got to window #1 




wnum 


maximum— windows 


MW 


Maximum number of definable windows 




xoffc 


xoff—character 


XF 


X-off character 


37 


xonc 


xon— character 


XN 


X-on character 


37 


zerom 


zero— motion 


Zx 


No motion for the subsequent character 


44 
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SAMPLE ENTRY 

The following entry, which describes the AT&T 610 terminal, is among the more 
complex entries in the terminfo file as of this writing. 

610 I 610bct I ATT610 | att610 | AT&T 610; 80 column; 98key keyboard 
am, eslok, hs, mir, msgr, xenl, xon, 

cols#80, it#8, lh#2, lines#24, lw#8, nlab#8, wsl#80, 
acsc= ' • aaf f gg j jkkllmmnnooppqqrrssttuuwwwxxyyzz { { | | } } ~ , 
bel='^G, blink=\E[5m, bold=\E[1m, cbt=\E[Z, 
civis=\E[?251, clear=\E[H\E[ J, cnorm=\E[ ?25h\E[ ? 121 , 
cr=\r, csr=\E[%i%p1%d;%p2%dr, cub=\E[%p1%dD, cub1=\b, 
cud=\E[%p1%dB, cud1=\E[B, cuf =\E[%p1%dC, cuf1=\E[C, 
cup=\E[%i%p1%d;%p2%dH, cuu=\E[%p1%dA, cuu1=\E[A, 
cwis=\E[?12;25h, dch=\E[%p1%dP , dch1=\E[P, dim=\E[2m, 
dl=\E[%p1%dM, dl1=\E[M, ed=\E[J, el=\E[K, el1=\E[lK, 
flash=\E[?5h$<200>\E[?51, fsl=\E8, home=\E[H, ht=\t, 
ich=\E[%p1%d@, il=\E[%p1%dL, il1=\E[L, ind=\ED, 
invis=\E[8m, 

is1=\E[8;0 I \E[?3;4;5;13;151\E[13;201\E[?7h\E[12h\E(B\E)0, 
is2=\E[Om'^0, is3=\E(B\E)0, kLFT=\E[\s@, kRIT=\E[\sA, 
kbs=\b, kcbt=\E[Z, kclr=\E[2J, kcub1=\E[D, kcud1=\E[B, 
kcuf1=\E[C, kcuu1=\E[A, kf1=\E0c, kf10=\ENp, 
kf11=\ENq, kf12=\ENr, kf13=\ENs, kf14=\ENt, kf2=\E0d, 
kf3=\E0e, kf4=\E0f, kf5=\E0g, kf6=\E0h, kf7=\E0i, 
kf8=\E0j, kf9=\ENo, khome=\E[H, kind=\E[S, kri=\E[T, 
11=\E[24H, mc4=\E[?4i, mc5=\E[?5i, nel=\EE, 
pfx=\E[%p1%d;%p2%l%02dq\s\s\sF%p1%1d\s\s\s\s\s 
\s\s\s\s\s\s%p2%s , 

pln=\E[%p1%d;0;0;0q%p2%:-16. 16s, rc=\E8, rev=\E[7m, 
ri=\EM, rmacs='^0, rmir=\E[41, rmln=\E[2p, rmso=\E[m, 
rmul=\E[m, rs2=\Ec\E[ ?31 , sc=\E7, 

sgr =\E [ 0%?%p6%t ; 1 % ; %?%p5%t ; 2% ; %?%p2%t ; 4% ; %?%p4%t ; 5% ; 
%?%p3%p1% I %t;7%;%?%p7%t;8%;m%?%p9%t'^N%e'^0%; , 
sgr0=\E[m'^O, smacs='^N, smir=\E[4h, smln=\E[p, 
smso=\E[7m, smul=\E[4m, tsl=\E7\E[25 ;%i%p1%dx. 

Types of Capabilities in the Sample Entry 

The sample entry shows the formats for the three types of terminfo capabilities 
listed: Boolean, Numeric, and String. The names of Boolean capabilities are 
often listed as abbreviations or acronyms, such as am (short for "automatic 
margins") in the sample entry. ("Automatic margins" is a short description of 
an automatic return and linefeed when the end of a line is reached.) 

Numeric capabilities are followed by the character and then the value. Thus, 
in the sample, cols (which shows the number of columns available on a 
terminal) gives the value 80 for the AT&T 610. (Values for numeric capabilities 
may be specified in decimal, octal or hexadecimal, using normal C conventions.) 

Finally, string-valued capabilities such as el (clear to end of line sequence) are 
listed by a two- to five-character capname, an '=', and a string ended by the 
next occurrence of a comma. A delay in milliseconds may appear an)rwhere in 
such a capability, enclosed in $<..> brackets, as in el=\EK$<3>. Padding 
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characters are supplied by tputs(). The delay can be any of the following: a 
number (5), a number followed by a (5*), a number followed by a (5/), or 
a number followed by both (5*/). A shows that the padding required is pro- 
portional to the number of lines affected by the operation, and the amount given 
is the per-affected-unit padding required. (In the case of insert characters, the 
factor is still the number of lines affected. This is always 1 unless the terminal 
has in and the software uses it.) When a is specified, it is sometimes useful 
to give a delay of the form 3.5 to specify a delay per unit to tenths of mil- 
liseconds. (Only one decimal place is allowed.) 

A y indicates that the padding is mandatory. Absence of a '/' is not shown, if 
the terminal has xon defined. Padding information is advisory and will be used 
only for cost estimates or when the terminal is in raw mode. Mandatory pad- 
ding will be transmitted regardless of the setting of xon. 

A number of escape sequences are provided in the string valued capabilities for 
easy encoding of characters there. Both \E and \e map to an ESCAPE character, 
maps to a control-x for any appropriate x, and the sequences \n, \1, \r, \t, 
\b, \f, and \s give a newline, linefeed, return, tab, backspace, formfeed, and 
space, respectively. Other escapes include: \" for caret ("); \\ for backslash 
(\); \, for comma (,); \: for colon (:); and \0 for null. (\0 will actually produce 
\200, which does not terminate a string but behaves as a null character on most 
terminals.) Finally, characters may be given as three octal digits after a 
backslash (e.g., \123). 

Sometimes individual capabilities must be commented out. To do this, put a 
period before the capability name. For example, see the second ind in the 
example above. Note that capabilities are defined in a left-to-right order and, 
therefore, a prior definition will override a later definition. 

Preparing Descriptions 

The most effective way to prepare a terminal description is by imitating the 
description of a similar terminal in tertninfo and to build up a description gradu- 
ally, using partial descriptions with vi{l) to check that they are correct. Be 
aware that a very unusual terminal may expose deficiencies in the ability of the 
terminfo file to describe it or the inability of vi{l) to work with that terminal. 
To test a new terminal description, set the environment variable TERMINFO to a 
pathname of a directory containing the compiled description you are working on 
and programs will look there rather than in /usr /lib /terminfo. To get the pad- 
ding for insert-line correct (if the terminal manufacturer did not document it) a 
severe test is to comment out xon, edit a large file at 9600 baud with vi{l), 
delete 16 or so lines from the middle of the screen, then hit the u key several 
times quickly. If the display is corrupted, more padding is usually needed. A 
similar test can be used for insert-character. 

Section 1-1: Basic Capabilities 

The number of columns on each line for the terminal is given by the cols 
numeric capability. If the terminal has a screen, then the number of lines on the 
screen is given by the lines capability. If the terminal can clear its screen, 
leaving the cursor in the home position, then this is given by the clear string 
capability. If the terminal overstrikes (rather than clearing a position when a 
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character is struck over) then it should have the os capability. If the terminal is 
a printing terminal, with no soft copy unit, give it both he and os. (os applies to 
storage scope terminals, such as the Tektronix 4010 series, as well as hard-copy 
and APL terminals.) If there is a code to move the cursor to the left edge of the 
current row, give this as cr, (Normally this will be carriage return, control M.) 
If there is a code to produce an audible signal (such as a bell or a beep), specify 
it as bel. If the terminal uses the xon-xoff flow-control protocol, like most ter- 
minals, specify xon. 

If there is a code to move the cursor one position to the left (such as backspace), 
that capability should be given as cubl. Similarly, codes to move to the right, 
up, and down should be given as cufl, cuul, and cudl. These local cursor 
motions should not alter the text they pass over; for example, you would not 
normally use "cufl=\s" because the space would erase the character moved 
over. 

A very important point here is that the local cursor motions encoded in terminfo 
are undefined at the left and top edges of a screen terminal. Programs should 
never attempt to backspace around the left edge, unless bw is given, and should 
never attempt to go up locally off the top. In order to scroll text up, a program 
will go to the bottom left comer of the screen and send the ind (index) string. 

To scroll text down, a program goes to the top left corner of the screen and 
sends the ri (reverse index) string. The strings ind and ri are undefined when 
not on their respective comers of the screen. 

Parameterized versions of the scrolling sequences are indn and rin which have 
the same semantics as ind and ri except that they take one parameter, and scroll 
that many lines. They are also undefined except at the appropriate edge of the 
screen. 

If the terminal wraps around to the beginning of the next line when it reaches 
the right margin, then it should have the am capability. The am capability tells 
whether the cursor sticks at the right edge of the screen when text is output, but 
this does not necessarily apply to a cufl from the last column. The only local 
motion which is defined from the left edge is if bw is given, then a cubl from 
the left edge will move to the right edge of the previous row. If bw is not 
given, the effect is undefined. This is useful for drawing a box around the edge 
of the screen, for example. If the terminal has switch selectable automatic mar- 
gins, the terminfo file usually assumes that this is on; i.e., am. If the terminal 
has a command which moves to the first column of the next line, that command 
can be given as nel (newline). It does not matter if the command clears the 
remainder of the current line, so if the terminal has no cr and If it may still be 
possible to craft a working nel out of one or both of them. 

These capabilities suffice to describe hardcopy and screen terminals. Thus the 
model 33 teleprinter is described as: 

She, OS, xon 
cols#72 , 

bel = '^G, cr = \r, cud1=\n, ind = \n, 



-25- 



TERMINFO(4) 



(Terminal Information Utilities) 



TERMINFO(4) 



while the Lear Siegler ADM-3 is described as: 

adm3 | Isi admS , 

am, bel = '^G, clear = '^Z, cols#80, cr='^M, cub1 = '^H, 
cud1 = '^J, ind='^J, lines#24, 

Section 1-2: Parameterized Strings 

Cursor addressir\g and other strings requiring parameters in the terminal are 
described by a parameterized string capability, with printf (3S)-\ike escapes (%x) 
in it. For example, to address the cursor, the cup capability is given, using two 
parameters: the row and column to address to. (Rows and columns are num- 
bered from zero and refer to the physical screen visible to the user, not to any 
unseen memory.) If the terminal has memory relative cursor addressing, that 
can be indicated by mrcup. 

The parameter mechanism uses a stack and special Vo codes to manipulate it in 
the manner of a Reverse Polish Notation (postfix) calculator. Typically a 
sequence will push one of the parameters onto the stack and then print it in 
some format. Often more complex operations are necessary. Binary operations 
are in postfix form with the operands in the usual order. That is, to get x-5 one 
would use %gx%{5}%-. 

The Vo encodings have the following meanings: 

%% outputs 
%[[:]flags][width[.precision]][doxXs] 

as in printf, flags are [-+#] and space 
%c print popO gives %c 

%p[l-9] push i^^ parm 



%P[a-z] set variable [a-z] to pop() 

%g[a-z] get variable [a-z] and push it 

%'c' push char constant c 

%{nn} push decimal constant nn 

%1 push strlen(pop()) 

%+ %- %* %/ %m 

arithmetic (%m is mod): push(pop() op pop()) 

%& %l % bit operations: push(pop() op pop()) 

%= %> %< logical operations: push(pop() op pop()) 

%A %0 logical operations: and, or 

%! %" unary operations: push(op pop()) 

%i (for ANSI terminals) 

add 1 to first parm, if one parm present, 

or first two parms, if more than one parm present 

%? expr %t thenpart %e elsepart %; 

if-then-else, %e elsepart is optional; 
else-if s are possible ala Algol 68: 

%? c^ %t b, %e c^ %t b^ %e c^ %t K %e c, %t b, %e \%; 

11223344 5 

c. are conditions, b. are bodies. 
1 ' 1 
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If the flag is used with "%[doxXs]", then a colon (:) must be placed between 
the "%" and the "-" to differentiate the flag from the binary operator 
.e.g., ''%:-16.16s". 

Consider the Hewlett-Packard 2645, which, to get to row 3 and column 12, 
needs to be sent \E&al2c03Y padded for 6 milliseconds. Note that the order of 
the rows and columns is inverted here, and that the row and column are zero- 
padded as two digits. Thus its cup capability is 
"cup=\E&a%p2%2.2dc%pl%2.2dY$<6>". 

The Micro-Term ACT-IV needs the current row and column sent preceded by a 
T, with the row and column simply encoded in binary, 
"cup="T%pl%c%p2%c". Terminals which use "%c" need to be able to back- 
space the cursor (cubl), and to move the cursor up one line on the screen 
(cuul). This is necessary because it is not always safe to transmit \n, "D, and 
\r, as the system may change or discard them. (The library routines dealing 
with terminfo set tty modes so that tabs are never expanded, so \t is safe to 
send. This turns out to be essential for the Ann Arbor 4080.) 

A final example is the LSI ADM-3a, which uses row and column offset by a blank 
character, thus "cup=\E=%pl%'\s'%+%c%p2%'\s'%+%c". After sending 
"\E=", this pushes the first parameter, pushes the ASCII value for a space (32), 
adds them (pushing the sum on the stack in place of the two previous values), 
and outputs that value as a character. Then the same is done for the second 
parameter. More complex arithmetic is possible using the stack. 

Section 1-3: Cursor Motions 

If the terminal has a fast way to home the cursor (to very upper left corner of 
screen) then this can be given as home; similarly a fast way of getting to the 
lower left-hand corner can be given as 11; this may involve going up with cuul 
from the home position, but a program should never do this itself (unless 11 
does) because it can make no assumption about the effect of moving up from 
the home position. Note that the home position is the same as addressing to 
(0,0): to the top left comer of the screen, not of memory. (Thus, the \EH 
sequence on Hewlett-Packard terminals cannot be used for home without losing 
some of the other features on the terminal.) 

If the terminal has row or column absolute-cursor addressing, these can be given 
as single parameter capabilities hpa (horizontal position absolute) and vpa (vert- 
ical position absolute). Sometimes these are shorter than the more general two- 
parameter sequence (as with the Hewlett-Packard 2645) and can be used in 
preference to cup. If there are parameterized local motions (e.g., move n spaces 
to the right) these can be given as cud, cub, cuf, and cuu with a single parame- 
ter indicating how many spaces to move. These are primarily useful if the 
terminal does not have cup, such as the Tektronix 4025. 

Section 1-4: Area Clears 

If the terminal can clear from the current position to the end of the line, leaving 
the cursor where it is, this should be given as el. If the terminal can clear from 
the beginning of the line to the current position inclusive, leaving the cursor 
where it is, this should be given as ell. If the terminal can clear from the 
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current position to the end of the display, then this should be given as ed. ed is 
only defined from the first column of a line. (Thus, it can be simulated by a 
request to delete a large number of lines, if a true ed is not available.) 

Section 1-5: Insert/Delete Line 

If the terminal can open a new blank line before the line where the cursor is, 
this should be given as ill; this is done only from the first position of a line. 
The cursor must then appear on the newly blank line. If the terminal can delete 
the line which the cursor is on, then this should be given as dll; this is done 
only from the first position on the line to be deleted. Versions of ill and dll 
which take a single parameter and insert or delete that many lines can be given 
as il and dl. 

If the terminal has a settable destructive scrolling region (like the VTIOO) the 
command to set this can be described with the csr capability, which takes two 
parameters: the top and bottom lines of the scrolling region. The cursor posi- 
tion is, alas, undefined after using this command. It is possible to get the effect 
of insert or delete line using this command ~ the sc and rc (save and restore 
cursor) commands are also useful. Inserting lines at the top or bottom of the 
screen can also be done using ri or ind on many terminals without a true 
insert/delete line, and is often faster even on terminals with those features. 

To determine whether a terminal has destructive scrolling regions or non- 
destructive scrolling regions, create a scrolling region in the middle of the screen, 
place data on the bottom line of the scrolling region, move the cursor to the top 
line of the scrolling region, and do a reverse index (ri) followed by a delete line 
(dll) or index (ind). If the data that was originally on the bottom line of the 
scrolling region was restored into the scrolling region by the dll or ind, then the 
terminal has non-destructive scrolling regions. Otherwise, it has destructive 
scrolling regions. Do not specify csr if the terminal has non-destructive scrolling 
regions, unless ind, ri, indn, rin, dl, and dll all simulate destructive scrolling. 

If the terminal has the ability to define a window as part of memory, which all 
commands affect, it should be given as the parameterized string wind. The four 
parameters are the starting and ending lines in memory and the starting and 
ending columns in memory, in that order. 

If the terminal can retain display memory above, then the da capability should 
be given; if display memory can be retained below, then db should be given. 
These indicate that deleting a line or scrolling a full screen may bring non-blank 
lines up from below or that scrolling back with ri may bring down non-blank 
lines. 



Section 1-6: Insert/Delete Character 

There are two basic kinds of intelligent terminals with respect to insert/delete 
character operations which can be described using terminfo. The most common 
insert/delete character operations affect only the characters on the current line 
and shift characters off the end of the line rigidly. Other terminals, such as the 
Concept 100 and the Perkin Elmer Owl, make a distinction between typed and 
untyped blanks on the screen, shifting upon an insert or delete only to an 



-28- 



TERMINFO(4) 



(Terminal Information Utilities) 



TERMINFO(4) 



untyped blank on the screen which is either eliminated, or expanded to two 
untyped blanks. You can determine the kind of terminal you have by clearing 
the screen and then typing text separated by cursor motions. Type "abc def ' 
using local cursor motions (not spaces) between the abc and the def. Then posi- 
tion the cursor before the abc and put the terminal in insert mode. If typing 
characters causes the rest of the line to shift rigidly and characters to fall off the 
end, then your terminal does not distinguish between blanks and untyped posi- 
tions. If the abc shifts over to the def which then move together around the 
end of the current line and onto the next as you insert, you have the second 
type of terminal, and should give the capability in, which stands for "insert 
null". While these are two logically separate attributes (one line versus multiline 
insert mode, and special treatment of untyped spaces) no terminals whose insert 
mode cannot be described with the single attribute have been seen. 

terminfo can describe both terminals which have an insert mode and terminals 
which send a simple sequence to open a blank position on the current line. 
Give as smir the sequence to get into insert mode. Give as rmir the sequence 
to leave insert mode. Now give as ichl any sequence needed to be sent just 
before sending the character to be inserted. Most terminals with a true insert 
mode will not give ichl; terminals which send a sequence to open a screen posi- 
tion should give it here. (If your terminal has both, insert mode is usually 
preferable to ichl. Do not give both unless the terminal actually requires both 
to be used in combination.) If post-insert padding is needed, give this as a 
number of milliseconds padding in ip (a string option). Any other sequence 
which may need to be sent after an insert of a single character may also be 
given in ip. If your terminal needs both to be placed into an 'insert mode' and a 
special code to precede each inserted character, then both smir/rmir and ichl 
can be given, and both will be used. The ich capability, with one parameter, n, 
will insert n blanks. 

If padding is necessary between characters typed while not in insert mode, give 
this as a number of milliseconds padding in rmp. 

It is occasionally necessary to move around while in insert mode to delete char- 
acters on the same line (e.g., if there is a tab after the insertion position). If your 
terminal allows motion while in insert mode you can give the capability mir to 
speed up inserting in this case. Omitting mir will affect only speed. Some ter- 
minals (notably Datamedia's) must not have mir because of the way their insert 
mode works. 

Finally, you can specify dchl to delete a single character, dch with one parame- 
ter, n, to delete n characters, and delete mode by giving smdc and rmdc to enter 
and exit delete mode (any mode the terminal needs to be placed in for dchl to 
work). 

A command to erase n characters (equivalent to outputting n blanks without 
moving the cursor) can be given as ech with one parameter. 

Section 1-7: Highlighting, Underlining, and Visible Bells 

Your terminal may have one or more kinds of display attributes that allow you 
to highlight selected characters when they appear on the screen. The following 
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display modes (shown with the names by which they are set) may be available: 
a blinking screen (blink), bold or extra-bright characters (bold), dim or half- 
bright characters (dim), blanking or invisible text (invis), protected text (prot), a 
reverse-video screen (rev), and an alternate character set (smacs to enter this 
mode and rmacs to exit it). (If a command is necessary before you can enter 
alternate character set mode, give the sequence in enacs or "enable alternate- 
character-set" mode.) Turning on any of these modes singly may or may not 
turn off other modes. 

If you set any display attributes for highlighting, you will also want to provide 
the capability for turning them off. To do so, set sgrO. 

You should choose one display method as standout mode [see curses(3X)] and use 
it to highlight error messages and other kinds of text to which you want to draw 
attention. Choose a form of display that provides strong contrast but that is 
easy on the eyes. (We recommend re verse- video plus half-bright or reverse- 
video alone.) The sequences to enter and exit standout mode are given as smso 
and rmso, respectively. If the code to change into or out of standout mode 
leaves one or even two blank spaces on the screen, as the TVI 912 and Teleray 
1061 do, then xmc should be given to tell how many spaces are left. 

Codes to begin underlining and end underlining can be given as smul and rmul 
, respectively. If the terminal has a code to underline the current character and 
move the cursor one space to the right, such as the Micro-Term MIME, this can 
be given as uc. 

For historical reasons, some programs interpret rmso, rmul to mean " turn off all 
attributes, " not just standout and underline, respectively. 

If there is a sequence to set arbitrary combinations of modes, this should be 
given as sgr (set attributes), taking nine parameters. Each parameter is either 
or non-zero, as the corresponding attribute is on or off. The nine parameters 
are, in order: standout, underline, reverse, blink, dim, bold, blank, protect, alter- 
nate character set. Not all modes need to be supported by sgr; only those for 
which corresponding separate attribute commands exist should be supported. 
(See the example at the end of this section.) 

Terminals with the "magic cookie" glitch (xmc) deposit special "cookies" when 
they receive mode-setting sequences, which affect the display algorithm rather 
than having extra bits for each character. Some terminals, such as the Hewlett- 
Packard 2621, automatically leave standout mode when they move to a new line 
or the cursor is addressed. Programs using standout mode should exit standout 
mode before moving the cursor or sending a newline, unless the msgr 
capability, asserting that it is safe to move in standout mode, is present. 

If the terminal has a way of flashing the screen to indicate an error quietly (a 
bell replacement), then this can be given as flash; it must not move the cursor. 
A good flash can be done by changing the screen into reverse video, pad for 200 
ms, then return the screen to normal video. 

If the cursor needs to be made more visible than normal when it is not on the 
bottom line (to make, for example, a non-blinking underline into an easier to 
find block or blinking underline) give this sequence as cvvis. The boolean chts 
should also be given. If there is a way to make the cursor completely invisible. 
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give that as civis. The capability cnorm should be given which undoes the 
effects of either of these modes. 

If the terminal needs to be in a special mode when running a program that uses 
these capabilities, the codes to enter and exit this mode can be given as smcup 
and rmcup. This arises, for example, from terminals, such as the Concept, with 
more than one page of memory. If the terminal has only memory relative cursor 
addressing and not screen relative cursor addressing, a one screen-sized window 
must be fixed into the terminal for cursor addressing to work properly. This is 
also used for the Tektronix 4025, where smcup sets the command character to 
be the one used by terminfo. If the smcup sequence will not restore the screen 
after a rmcup sequence is output (to the state prior to outputting rmcup), specify 
nrrmc. 

If your terminal generates underlined characters by using the underline character 
(with no special codes needed) even though it does not otherwise overstrike 
characters, then you should give the capability ul. For terminals where a char- 
acter overstriking another leaves both characters on the screen, give the capabil- 
ity OS. If overs trikes are erasable with a blank, then this should be indicated by 
giving 80. 

Example of highlighting: assume that the terminal under question needs the fol- 
lowing escape sequences to turn on various modes. 



tparm 
parameter 


attribute 


escape sequence 




none 


\E[Om 


pi 


standout 


\E[0;4;7m 


P2 


underline 


\E[0;3m 


p3 


reverse 


\E[0;4m 


p4 


blink 


\E[0;5m 


p5 


dim 


\E[0;7m 


p6 


bold 


\E[0;3;4m 


P7 


invis 


\E[0;8m 


p8 


protect 


not available 


P9 


altcharset 


(off) ^N(on) 



Note that each escape sequence requires a to turn off other modes before turn- 
ing on its own mode. Also note that, as suggested above, standout is set up to 
be the combination of reverse and dim. Also, because this terminal has no bold 
mode, bold is set up as the combination of reverse and underline. In addition, to 
allow combinations, such as underline -\rblink , the sequence to use would be 
\E[0;3;5m. The terminal doesn't have protect mode, either, but that cannot be 
simulated in any way, so p8 is ignored. The altcharset mode is different in that 
it is either "O or "N, depending on whether it is off or on. If all modes were to 
be turned on, the sequence would be \E[0;3;4;5;7;8m"N. 

Now look at when different sequences are output. For example, ;3 is output 
when either p2 or p6 is true, that is, if either underline or bold modes are turned 
on. Writing out the above sequences, along with their dependencies, gives the 
following: 
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sequence 


when to output 


terminfo translation 


\E[0 


always 


\E[0 

%?%p2%p6%l%t;3%; 


;3 


if p2 or p6 


;4 


if pi or p3 or p6 


%?%pl%p3%l%p6%l%t;4%; 


;5 


if p4 


%?%p4%t;5%; 


;7 


if pi or p5 


%?%pl%p5%l%t;7%; 


;8 


if p7 


%?%p7%t;8%; 


m 


always 


m 


or 


if p9 "N, else 


%?%p9%t " N%e " 0%; 



Putting this all together into the sgr sequence gives: 

sgr=\E[0%?%p2%p6%l%t;3%;%?%pl%p3%!%p6%l%t;4%;%?%p5%t;5%; 
%?%pl%p5%l%t;7%;%?%p7%t;8%;m%?%p9%t^N%e^O%;, 

Section 1-8: Keypad 

If the terminal has a keypad that transmits codes when the keys are pressed, this 
information can be given. Note that it is not possible to handle terminals where 
the keypad only works in local (this applies, for example, to the unshifted 
Hewlett-Packard 2621 keys). If the keypad can be set to transmit or not 
transmit, give these codes as smkx and rmkx. Otherwise the keypad is assumed 
to transmit. 

The codes sent by the left arrow, right arrow, up arrow, down arrow, and home 
keys can be given as kcubl, kcufl, kcuul, kcudl, and khome respectively. If 
there are function keys such as fO, fl, f63, the codes they send can be given 
as kfO, kfl, kf63. If the first 11 keys have labels other than the default fO 
through flO, the labels can be given as IfO, Ifl, If 10. The codes transmitted 
by certain other special keys can be given: kll (home down), kbs (backspace), 
ktbc (clear all tabs), kctab (clear the tab stop in this column), kclr (clear screen 
or erase key), kdchl (delete character), kdll (delete line), krmir (exit insert 
mode), kel (clear to end of line), ked (clear to end of screen), kichl (insert char- 
acter or enter insert mode), kill (insert line), knp (next page), kpp (previous 
page), kind (scroll forward/down), kri (scroll backward/up), khts (set a tab stop 
in this column). In addition, if the keypad has a 3 by 3 array of keys including 
the four arrow keys, the other five keys can be given as kal, ka3, kb2, kcl, and 
kc3. These keys are useful when the effects of a 3 by 3 directional pad are 
needed. Further keys are defined above in the capabilities list. 

Strings to program function keys can be given as pfkey, pfloc, and pfx. A 
string to program their soft-screen labels can be given as pin. Each of these 
strings takes two parameters: the function key number to program (from to 10) 
and the string to program it with. Function key numbers out of this range may 
program undefined keys in a terminal-dependent manner. The difference 
between the capabilities is that pfkey causes pressing the given key to be the 
same as the user typing the given string; pfloc causes the string to be executed 
by the terminal in local mode; and pfx causes the string to be transmitted to the 
computer. The capabilities nlab, Iw, and Ih define how many soft labels there 
are and their width and height. If there are commands to turn the labels on and 
off, give them in smln and rmln. smln is normally output after one or more 
pin sequences to make sure that the change becomes visible. 
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Section 1-9: Tabs and Initialization 

If the terminal has hardware tabs, the command to advance to the next tab stop 
can be given as ht (usually control I). A "backtab" command which moves left- 
ward to the next tab stop can be given as cbt. By convention, if the teletype 
modes indicate that tabs are being expanded by the computer rather than being 
sent to the terminal, programs should not use ht or cbt even if they are present, 
since the user may not have the tab stops properly set. If the terminal has 
hardware tabs which are initially set every n spaces when the terminal is 
powered up, the numeric parameter it is given, showing the number of spaces 
the tabs are set to. This is normally used by tput init [see tput{l)] to determine 
whether to set the mode for hardware tab expansion and whether to set the tab 
stops. If the terminal has tab stops that can be saved in nonvolatile memory, 
the terminfo description can assume that they are properly set. If there are com- 
mands to set and clear tab stops, they can be given as tbc (clear all tab stops) 
and hts (set a tab stop in the current column of every row). 

Other capabilities include: isl, is2, and is3, initialization strings for the terminal; 
iprog, the path name of a program to be run to initialize the terminal; and if, 
the name of a file containing long initialization strings. These strings are 
expected to set the terminal into modes consistent with the rest of the terminfo 
description. They must be sent to the terminal each time the user logs in and be 
output in the following order: run the program iprog; output isl; output is2; set 
the margins using mgc, smgl, and smgr; set the tabs using tbc and hts; print the 
file if; and finally output is3. This is usually done using the init option of 
tput{l); see profile (4). 

Most initialization is done with is2. Special terminal modes can be set up 
without duplicating strings by putting the common sequences in is2 and special 
cases in isl and is3. Sequences that do a harder reset from a totally unknown 
state can be given as rsl, rs2, rf, and rs3, analogous to isl, is2, is3, and if. (The 
method using files, if and rf, is used for a few terminals, from /usr/lib/tabset/*; 
however, the recommended method is to use the initialization and reset strings.) 
These strings are output by tput reset, which is used when the terminal gets 
into a wedged state. Commands are normally placed in rsl, rs2, rs3, and rf only 
if they produce annoying effects on the screen and are not necessary when log- 
ging in. For example, the command to set a terminal into 80-column mode 
would normally be part of is2, but on some terminals it causes an annoying 
glitch on the screen and is not normally needed since the terminal is usually 
already in 80-column mode. 

If a more complex sequence is needed to set the tabs than can be described by 
using tbc and hts, the sequence can be placed in is2 or if. 

Any margin can be cleared with mgc. (For instructions on how to specify com- 
mands to set and clear margins, see "Margins" below under "PRINTER 
CAPABILITIES.") 

Section 1-10: Delays 

Certain capabilities control padding in the tty{7) driver. These are primarily 
needed by hard-copy terminals, and are used by tput init to set tty modes 
appropriately. Delays embedded in the capabilities cr, ind, cubl, ff, and tab can 
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be used to set the appropriate delay bits to be set in the tty driver. If pb (pad- 
ding baud rate) is given, these values can be ignored at baud rates below the 
value of pb. 

Section 1-11: Status Lines 

If the terminal has an extra "status line" that is not normally used by software, 
this fact can be indicated. If the status line is viewed as an extra line below the 
bottom line, into which one can cursor address normally (such as the Heathkit 
hl9's 25th line, or the 24th line of a VTIOO which is set to a 23-line scrolling 
region), the capability hs should be given. Special strings that go to a given 
column of the status line and return from the status line can be given as tsl and 
fsl. (fsl must leave the cursor position in the same place it was before tsl. If 
necessary, the sc and rc strings can be included in tsl and fsl to get this effect.) 
The capability tsl takes one parameter, which is the column number of the 
status line the cursor is to be moved to. 

If escape sequences and other special commands, such as tab, work while in the 
status line, the flag eslok can be given. A string which turns off the status line 
(or otherwise erases its contents) should be given as dsl. If the terminal has 
commands to save and restore the position of the cursor, give them as sc and rc. 
The status line is normally assumed to be the same width as the rest of the 
screen, e.g., cols. If the status line is a different width (possibly because the ter- 
minal does not allow an entire line to be loaded) the width, in columns, can be 
indicated with the numeric parameter wsl. 

Section 1-12: Line Graphics 

If the terminal has a line drawing alternate character set, the mapping of glyph 
to character would be given in acsc. The definition of this string is based on the 
alternate character set used in the DEC VTIOO terminal, extended slightly with 
some characters from the AT&T 4410vl terminal. 

glyph name 

arrow pointing right 
arrow pointing left 
arrow pointing down 
solid square block 
lantern symbol 
arrow pointing up 
diamond 

checker board (stipple) 
degree symbol 
plus/minus 
board of squares 
lower right corner 
upper right corner 
upper left comer 
lower left corner 
plus 

scan line 1 
horizontal line 



vtlOO+ 
character 
+ 


I 

a 
f 

g 
h 

j 

k 
1 

m 
n 
o 

q 
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scan line 9 s 

left tee ( I- ) t 

right tee (-1) u 

bottom tee ( J_) v 

top tee (t) w 

vertical line x 
bullet 



The best way to describe a new terminal's line graphics set is to add a third 
column to the above table with the characters for the new terminal that produce 
the appropriate glyph when the terminal is in the alternate character set mode. 
For example, 

, , vtlOOH- new tty 

g yp name character character 

upper left corner 1 R 

lower left corner m F 

upper right corner k T 

lower right corner j G 

horizontal line q , 

vertical line x 



Now write down the characters left to right, as in "acsc=lRmFkTjGq\,x/'. 

In addition, terminfo allows you to define multiple character sets. See 
Section 2-5 for details. 

Section 1-13: Color Manipulation 

There are two methods of color manipulation: the HP method and the Tek- 
tronix method. Most existing color terminals belong to one of these two classes. 

The Tektronix method uses a set of N predefined colors (usually 8) from which 
a user can select "current" foreground and background colors. Thus the termi- 
nal can support up to N colors mixed into N*N color-pairs to be displayed on 
the screen at the same time. 

The HP method restricts the user from defining the foreground independently of 
the background, or vice- versa. Instead, the user must define an entire color-pair 
at once. Up to M color-pairs, made from 2*M different colors, can be defined 
this way. 

The numeric variables colors and pairs define the number of colors and color- 
pairs that can be displayed on the screen at the same time. If a terminal can 
change the definition of a color (as can, for example, the Tektronix 4100 and 
4200 series terminals), this should be specified with ccc (can change color). To 
change the definition of a color (Tektronix method), use initc (initialize color). 
It requires four arguments: color number (ranging from to colors-1) and three 
RGB (red, green, and blue) values (ranging from to 1,000). 

Tektronix 4100 series terminals use a type of color notation called HLS (Hue 
Lightness Saturation) instead of RGB color notation. For such terminals one 
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must define a boolean variable his. The last three arguments to the initc string 
would then be HLS values: H, ranging from to 360; and L and S, ranging 
from to 100. 

If a terminal can change the definitions of colors, but uses a color notation dif- 
ferent from RGB and HLS, a mapping to either RGB or HLS must be developed. 

To set current foreground or background to a given color, use setff (set fore- 
ground) and setb (set background). They require one parameter: the number of 
the color. To initialize a color-pair (HP method), use initp (initialize pair). It 
requires seven parameters: the number of a color-pair (range = to pairs-1), 
and six RGB values: three for the foreground followed by three for the back- 
ground. (Each of these groups of three should be in the order RGB.) When 
initc or initp are used, RGB or HLS arguments should be in the order "red, 
green, blue" or "hue, lightness, saturation"), respectively. To make a color-pair 
current, use sop (set color-pair). It takes one parameter, the number of a color- 
pair. 

Some terminals (for example, most color terminal emulators for PCs) erase areas 
of the screen with current background color. In such cases, bee (background 
color erase) should be defined. The variable op (original pair) contains a 
sequence for setting the foreground and the background colors to what they 
were at the terminal start-up time. Similarly, oc (original colors) contains a con- 
trol sequence for setting all colors (for the Tektronix method) or color-pairs (for 
the HP method) to the values they had at the terminal start-up time. 

Some color terminals substitute color for video attributes. Such video attributes 
should not be combined with colors. Information about these video attributes 
should be packed into the ncv (no color video) variable. There is a one-to-one 
correspondence between the nine least significant bits of that variable and the 
video attributes. The following table depicts this correspondence. 

NCV Bit 



Attribute 



Number 



A_STANDOUT 

A_UNDERLINE 1 

A_REVERSE 2 

A_BLINK 3 

A_DIM 4 

A_BOLD 5 

A_INVIS 6 

A_PROTECT 7 

A_ALTCHARSET 8 



When a particular video attribute should not be used with colors, the 
corresponding ncv bit should be set to 1; otherwise it should be set to zero. For 
example, if the terminal uses colors to simulate reverse video and bold, bits 2 
and 5 should be set to 1. The resulting values for ncv will be 22. 

Section 1-14: Miscellaneous 

If the terminal requires other than a null (zero) character as a pad, then this can 
be given as pad. Only the first character of the pad string is used. If the termi- 
nal does not have a pad character, specify npc. 
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If the terminal can move up or down half a line, this can be indicated with hu 
(half-line up) and hd (half-line down). This is primarily useful for superscripts 
and subscripts on hardcopy terminals. If a hardcopy terminal can eject to the 
next page (form feed), give this as ff (usually control L). 

If there is a command to repeat a given character a given number of times (to 
save time transmitting a large number of identical characters) this can be indi- 
cated with the parameterized string rep. The first parameter is the character to 
be repeated and the second is the number of times to repeat it. Thus, 
tparm(repeat_-char, 'x', 10) is the same as xxxxxxxxxx. 

If the terminal has a settable command character, such as the Tektronix 4025, 
this can be indicated with cmdch. A prototype command character is chosen 
which is used in all capabilities. This character is given in the cmdch capability 
to identify it. The following convention is supported on some UNIX systems: If 
the environment variable CC exists, all occurrences of the prototype character 
are replaced with the character in CC. 

Terminal descriptions that do not represent a specific kind of known terminal, 
such as switch, dialup, patch, and network, should include the gn (generic) 
capability so that programs can complain that they do not know how to talk to 
the terminal. (This capability does not apply to virtual terminal descriptions for 
which the escape sequences are known.) If the terminal is one of those sup- 
ported by the UNIX system virtual terminal protocol, the terminal number can be 
given as vt. A line-turn-around sequence to be transmitted before doing reads 
should be specified in rfi. 

If the terminal uses xon/xoff handshaking for flow control, give xon. Padding 
information should still be included so that routines can make better decisions 
about costs, but actual pad characters will not be transmitted. Sequences to turn 
on and off xon/xoff handshaking may be given in smxon and rmxon. If the 
characters used for handshaking are not "S and "Q, they may be specified with 
xonc and xoffc. 

If the terminal has a "meta key" which acts as a shift key, setting the 8th bit of 
any character transmitted, this fact can be indicated with km. Otherwise, 
software will assume that the 8th bit is parity and it will usually be cleared. If 
strings exist to turn this ''meta mode" on and off, they can be given as smm and 
rmm. 

If the terminal has more lines of memory than will fit on the screen at once, the 
number of lines of memory can be indicated with Im. A value of lm#0 
indicates that the number of lines is not fixed, but that there is still more 
memory than fits on the screen. 

Media copy strings which control an auxiliary printer connected to the terminal 
can be given as mcO: print the contents of the screen, mc4: turn off the printer, 
and mc5: turn on the printer. When the printer is on, all text sent to the termi- 
nal will be sent to the printer. A variation, mc5p, takes one parameter, and 
leaves the printer on for as many characters as the value of the parameter, then 
turns the printer off. The parameter should not exceed 255. If the text is not 
displayed on the terminal screen when the printer is on, specify mc5i (silent 
printer). All text, including mc4, is transparently passed to the printer while an 
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mc5p is in effect. 

Section 1-15: Special Cases 

The working model used by terminfo fits most terminals reasonably well. How- 
ever, some terminals do not completely match that model, requiring special sup- 
port by terminfo. These are not to be construed as deficiencies in the terminals; 
they are just differences between the working model and the actual hardware. 
They may be unusual devices or, for some reason, do not have all the features 
of the terminfo model implemented. 

Terminals which can not display tilde (") characters, such as certain Hazeltine 
terminals, should indicate hz. 

Terminals which ignore a linefeed immediately after an am wrap, such as the 
Concept 100, should indicate xenl. Those terminals whose cursor remains on 
the right-most column until another character has been received, rather than 
wrapping immediately upon receiving the right-most character, such as the 
VTIOO, should also indicate xenl. 

If el is required to get rid of standout (instead of writing normal text on top of 
it), xhp should be given. 

Those Teleray terminals whose tabs turn all characters moved over to blanks, 
should indicate xt (destructive tabs). This capability is also taken to mean that it 
is not possible to position the cursor on top of a ''magic cookie" therefore, to 
erase standout mode, it is instead necessary to use delete and insert line. 

Those Beehive Superbee terminals which do not transmit the escape or 
control-C characters, should specify xsb, indicating that the fl key is to be used 
for escape and the f2 key for control-C. 

Section 1-16: Similar Terminals 

If there are two very similar terminals, one can be defined as being just like the 
other with certain exceptions. The string capability use can be given with the 
name of the similar terminal. The capabilities given before use override those in 
the terminal type invoked by use. A capability can be canceled by placing xx@ 
to the left of the capability definition, where xx is the capability. For example, 
the entry 

att4424-2 I Teletype 4424 in display function group 
ii, rev@, sgr(5), smul@, use = att4424, 

defines an AT&T 4424 terminal that does not have the rev, sgr, and smul capa- 
bilities, and hence cannot do highlighting. This is useful for different modes for 
a terminal, or for different user preferences. More than one use capability may 
be given. 

PART 2: PRINTER CAPABILITIES 

The terminfo database allows you to define capabilities of printers as well as 
terminals. To find out what capabilities are available for printers as well as for 
terminals, see the two lists under "TERMINAL CAPABILITIES" that list 
capabilities by variable and by capability name. 

Section 2-1: Rounding Values 

Because parameterized string capabilities work only with integer values, we 
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recommend that terminfo designers create strings that expect numeric values that 
have been rounded. Application designers should note this and should always 
round values to the nearest integer before using them with a parameterized 
string capability. 

Section 2-2: Printer Resolution 

A printer's resolution is defined to be the smallest spacing of characters it can 
achieve. In general printers have independent resolution horizontally and verti- 
cally. Thus the vertical resolution of a printer can be determined by measuring 
the smallest achievable distance between consecutive printing baselines, while 
the horizontal resolution can be determined by measuring the smallest achiev- 
able distance between the left-most edges of consecutive printed, identical, char- 
acters. 

All printers are assumed to be capable of printing with a uniform horizontal and 
vertical resolution. The view of printing that the terminfo currently presents is 
one of printing inside a uniform matrix: All characters are printed at fixed posi- 
tions relative to each "cell" in the matrix; furthermore, each cell has the same 
size given by the smallest horizontal and vertical step sizes dictated by the reso- 
lution. (The cell size can be changed as will be seen later.) 

Many printers are capable of "proportional printing," where the horizontal spac- 
ing depends on the size of the character last printed. The terminfo does not 
make use of this capability, although it does provide enough capability defini- 
tions to allow an application to simulate proportional printing. 

A printer must not only be able to print characters as close together as the hor- 
izontal and vertical resolutions suggest, but also of "moving" to a position an 
integral multiple of the smallest distance away from a previous position. Thus 
printed characters can be spaced apart a distance that is an integral multiple of 
the smallest distance, up to the length or width of a single page. 
Some printers can have different resolutions depending on different "modes." 
In "normal mode," the existing terminfo capabilities are assumed to work on 
columns and lines, just like a video terminal. Thus the old lines capability 
would give the length of a page in lines, and the cols capability would give the 
width of a page in columns. In "micro mode," many terminfo capabilities work 
on increments of lines and columns. With some printers the micro mode may 
be concomitant with normal mode, so that all the capabilities work at the same 
time. 

Section 2-3: Specifying Printer Resolution 

The printing resolution of a printer is given in several ways. Each specifies the 
resolution as the number of smallest steps per distance: 

Specification of Printer Resolution 
Characteristic Number of Smallest Steps 

orhi Steps per inch horizontally 

orvi Steps per inch vertically 

ore Steps per column 

orl Steps per line 
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When printing in normal mode, each character printed causes movement to the 
next column, except in special cases described later; the distance moved is the 
same as the per-column resolution. Some printers cause an automatic move- 
ment to the next line when a character is printed in the rightmost position; the 
distance moved vertically is the same as the per-line resolution. When printing 
in micro mode, these distances can be different, and may be zero for some 
printers. 

Specification of Printer Resolution 
Automatic Motion after Printin g 
Normal Mode: 

ore Steps moved horizontally 
orl Steps moved vertically 

Micro Mode: 

mcs Steps moved horizontally 
mis Steps moved vertically 

Some printers are capable of printing wide characters. The distance moved 
when a wide character is printed in normal mode may be different from when a 
regular width character is printed. The distance moved when a wide character is 
printed in micro mode may also be different from when a regular character is 
printed in micro mode, but the differences are assumed to be related: If the dis- 
tance moved for a regular character is the same whether in normal mode or 
micro mode (mcs=orc), then the distance moved for a wide character is also the 
same whether in normal mode or micro mode. This doesn't mean the normal 
character distance is necessarily the same as the wide character distance, just 
that the distances don't change with a change in normal to micro mode. How- 
ever, if the distance moved for a regular character is different in micro mode 
from the distance moved in normal mode (mcs<orc), the micro mode distance is 
assumed to be the same for a wide character printed in micro mode, as the table 
below shows. 

Specification of Printer Resolution 
Automatic Motion after Printing Wide Chara cter 
Normal Mode or Micro Mode (mcs = ore): 
wides Steps moved horizontally 

Micro Mode (mes < ore); 

mes. Steps moved horizontally 

There may be control sequences to change the number of columns per inch (the 
character pitch) and to change the number of lines per inch (the line pitch). If 
these are used, the resolution of the printer changes, but the type of change 
depends on the printer: 

Specification of Printer Resolution 

Changing the Character/Line Pitches 

epi Change character pitch 

cpix If set, epi changes orhi, otherwise changes ore 
Ipi Change line pitch 
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Ipix If set, ipi changes orvi, otherwise changes orl 

chr Change steps per column 
cvr Change steps per line 

The cpi and Ipi string capabilities are each used with a single argument, the 
pitch in columns (or characters) and lines per inch, respectively. The chr and 
cvr string capabilities are each used with a single argument, the number of steps 
per column and line, respectively. 

Using any of the control sequences in these strings will imply a change in some 
of the values of ore, orhi, orl, and orvi. Also, the distance moved when a wide 
character is printed, widcs, changes in relation to ore. The distance moved 
when a character is printed in micro mode, mcs, changes similarly, with one 
exception: if the distance is or 1, then no change is assumed (see item marked 
with I in the following table). 

Programs that use cpi, Ipi, chr, or cvr should recalculate the printer resolution 
(and should recalculate other values — see "Section 2-7: Effect of Changing 
Printing Resolution"). 

Specification of Printer Resolution 
Effects of Changing the Character/Line Pitches 

Before After 

Using cpi with cpix clear: 
orhi' 

ore ' 

Using cpi with cpix set: 
orhi' 
ore ' 

Using Ipi with Ipix clear: 
orvi ' 

orl' 

Using Ipi with Ipix set: 
orvi ' 
orl' 

Using chr: 
orhi' 
ore ' 

Using cvr: 
orvi ' 
orl' 



orhi 

orhi 
orc= 

V ■ 



orhi=orc*Vcpi 
ore 



orvi 

orvi 



orl=- 



Vipi 



orvi=oriy/p, 
orl 



orhi 

Vchr 



orvi 

V 

' cvr 
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Using cpi or chr: 

widcs ' widcs=widcs'-^^ 

ore' 

ore 

mcs't mcs=mcs' 

ore' 

^cpif ^ipir ychrr and Vcvr are the arguments used with epi, Ipi, ehr, and evr 
respectively. The f mark indicates the old value. 

Section 2-4: Capabilities that Cause Movement 

In the following descriptions, "movement" refers to the motion of the "current 
position." With video terminals this would be the cursor; with some printers 
this is the carriage position. Other printers have different equivalents. In gen- 
eral, the current position is where a character would be displayed if printed. 

terminfo has string capabilities for control sequences that cause movement a 
number of full columns or lines. It also has equivalent string capabilities for 
control sequences that cause movement a number of smallest steps. 

String Capabilities for Motion 

mcubl Move 1 step left 

mcufl Move 1 step right 

mcuul Move 1 step up 

mcudl Move 1 step down 

mcub Move N steps left 

mcuf Move N steps right 

mcuu Move N steps up 

mcud Move N steps down 

mhpa Move N steps from the left 
mvpa Move N steps from the top 

The latter six strings are each used with a single argument, N. 

Sometimes the motion is limited to less than the width or length of a page. 
Also, some printers don't accept absolute motion to the left of the current posi- 
tion, terminfo has capabilities for specifying these limits. 

Limits to Motion 

mjump Limit on use of mcubl, mcufl, mcuul, mcudl 
maddr Limit on use of mhpa, mvpa 

xhpa If set, hpa and mhpa can't move left 
xvpa If set, vpa and mvpa can't move up 

If a printer needs to be in a "micro mode" for the motion capabilities described 
above to work, there are string capabilities defined to contain the control 
sequence to enter and exit this mode. A boolean is available for those printers 
where using a carriage return causes an automatic return to normal mode. 
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Entering/Exiting Micro Mode 

smicm Enter micro mode 
rmicm Exit micro mode 

crxm Using cr exits micro mode 

The movement made when a character is printed in the rightmost position varies 
among printers. Some make no movement, some move to the beginning of the 
next line, others move to the beginning of the same line, terminfo has boolean 
capabilities for describing all three cases. 

What Happens After Character 

Printe d in Rightmost Position 

sam Automatic move to beginning of same line 



Some printers can be put in a mode where the normal direction of motion is 
reversed. This mode can be especially useful when there exists no capabilities 
for leftward or upward motion, because those capabilities can be built from the 
motion reversal capability and the rightward or downward motion capabilities. 
It is best to leave it up to an application to build the leftward or upward capabil- 
ities, though, and not enter them in the terminfo database. This allows several 
reverse motions to be strung together without intervening wasted steps that 
leave and reenter reverse mode. 



Entering/Exiting Reverse Modes 



slm 


Reverse sense of horizontal motions 


rim 


Restore sense of horizontal motions 


sum 


Reverse sense of vertical motions 


rum 


Restore sense of vertical motions 


While sense of horizontal motions reversed: 


mcubl 


Move 1 step right 


mcufl 


Move 1 step left 


mcub 


Move N steps right 


mcuf 


Move N steps left 


cubl 


Move 1 column right 


cufl 


Move 1 column left 


cub 


Move N columns right 


cuf 


Move N columns left 


While sense of vertical motions reversed: 


mcuul 


Move 1 step down 


mcudl 


Move 1 step up 


mcuu 


Move N steps down 


mcud 


Move N steps up 


cuul 


Move 1 line down 


cudl 


Move 1 line up 


cuu 


Move N lines down 


cud 


Move N lines up 
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The reverse motion modes should not affect the mvpa and mhpa absolute 
motion capabilities. The reverse vertical motion mode should, however, also 
reverse the action of the line "wrapping" that occurs when a character is printed 
in the right-most position. Thus printers that have the standard terminfo capa- 
bility am defined should experience motion to the beginning of the previous line 
when a character is printed in the right-most position under reverse vertical 
motion mode. 

The action when any other motion capabilities are used in reverse motion modes 
is not defined; thus, programs must exit reverse motion modes before using 
other motion capabilities. 

Two miscellaneous capabilities complete the list of new motion capabilities. 
One of these is needed for printers that move the current position to the begin- 
ning of a line when certain control characters, like 'Tine-feed" or "form-feed," 
are used. The other is used for the capability of suspending the motion that 
normally occurs after printing a character. 

Miscellaneous Motion S trings 

doer List of control characters causing cr 

zerom Prevent auto motion after printing next single character 

Margins 

terminfo provides two strings for setting margins on terminals: one for the left 
and one for the right margin. Printers, however, have two additional margins, 
for the top and bottom margins of each page. Furthermore, some printers do 
not require using motion strings to move the current position to a margin and 
fixing the margin there, as with the existing capabilities, but require the specifi- 
cation of where a margin should be regardless of the current position. Therefore 
terminfo offers six additional strings for defining margins with printers. 

Setting Margins 

smgl Set left margin at current column 
smgr Set right margin at current column 

smgb Set soft bottom margin at current line 
smgt Set soft top margin at current line 

smgbp Set soft bottom margin at line N 

smglp Set soft left margin at column N 

smgrp Set soft right margin at column N 

smgtp Set soft top margin at line N 

The last four strings are used with a single argument, N, that gives the line or 
column number, where line is the top line and column is the left-most 
column. Note: Not all printers use for the top line or the left-most column. 

All margins can be cleared with mgc. 

Shadows, Italics, Wide Characters, Superscripts, Subscripts 

Five new sets of strings are used to describe the capabilities printers have of 
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enhancing printed text. 



Enhanced Printing 



sshm 
rshm 

sitm 
ritm 



Enter shadow-printing mode 
Exit shadow-printing mode 



Enter italicizing mode 
Exit italicizing mode 



swidm Enter wide character mode 

rwidm Exit wide character mode 

ssupm Enter superscript mode 

rsupm Exit superscript mode 

supcs List of characters available as superscripts 

ssubm Enter subscript mode 

rsubm Exit subscript mode 

subcs List of characters available as subscripts 



If a printer requires the sshm control sequence before every character to be 
shadow-printed, the rshm string is left blank. Thus programs that find a control 
sequence in sshm but none in rshm should use the sshm control sequence 
before every character to be shadow-printed; otherwise, the sshm control 
sequence should be used once before the set of characters to be shadow-printed, 
followed by rshm. The same is also true of each of the sitm/ritm, 
swidm/rwidm, ssupm/rsupm, and ssubm/rsubm pairs. 

Note that terminfo also has a capability for printing emboldened text (bold). 
While shadow printing and emboldened printing are similar in that they 
''darken" the text, many printers produce these two types of print in slightly dif- 
ferent ways. Generally, emboldened printing is done by overstriking the same 
character one or more times. Shadow printing likewise usually involves over- 
striking, but with a slight movement up and/or to the side so that the character 
is "fatter." 

It is assumed that enhanced printing modes are independent modes, so that it 
would be possible, for instance, to shadow print italicized subscripts. 

As mentioned earlier, the amount of motion automatically made after printing a 
wide character should be given in widcs. 

If only a subset of the printable ASCII characters can be printed as superscripts 
or subscripts, they should be listed in supcs or subcs strings, respectively. If the 
ssupm or ssubm strings contain control sequences, but the corresponding supcs 
or subcs strings are empty, it is assumed that all printable ASCII characters are 
available as superscripts or subscripts. 

Automatic motion made after printing a superscript or subscript is assumed to be 
the same as for regular characters. Thus, for example, printing any of the 
following three examples will result in equivalent motion: 



Note that the existing msgr boolean capability describes whether motion control 
sequences can be used while in "standout mode." This capability is extended to 



Bi B. B' 
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cover the enhanced printing modes added here, msgr should be set for those 
printers that accept any motion control sequences without affecting shadow, ital- 
icized, widened, superscript, or subscript printing. Conversely, if msgr is not 
set, a program should end these modes before attempting any motion. 

Section 2-5: Alternate Character Sets 

In addition to allowing you to define line graphics (described in Section 1-12), 
terminfo also lets you define alternate character sets. The following capabilities 
cover printers and terminals with multiple selectable or definable character sets. 

Alternate Character Sets 

scs Select character set N 

scsd Start definition of character set N, M characters 

defc Define character A, B dots wide, descender D 

rcsd End definition of character set N 

csnm List of character set names 

daisy Printer has manually changed print-wheels 

The scs, rcsd, and csnm strings are used with a single argument, N, a number 
from to 63 that identifies the character set. The scsd string is also used with 
the argument N and another, M, that gives the number of characters in the set. 
The defc string is used with three arguments: A gives the ASCII code represen- 
tation for the character, B gives the width of the character in dots, and D is zero 
or one depending on whether the character is a ''descender" or not. The defc 
string is also followed by a string of "image-data" bytes that describe how the 
character looks (see below). 

Character set is the default character set present after the printer has been ini- 
tialized. Not every printer has 64 character sets, of course; using scs with an 
argument that doesn't select an available character set should cause a null result 
from tparm(). 

If a character set has to be defined before it can be used, the scsd control 
sequence is to be used before defining the character set, and the rcsd is to be 
used after. They should also cause a null result from tparm{) when used with 
an argument N that doesn't apply. If a character set still has to be selected after 
being defined, the scs control sequence should follow the rcsd control sequence. 
By examining the results of using each of the scs, scsd, and rcsd strings with a 
character set number in a call to tparm(), a program can determine which of the 
three are needed. 

Between use of the scsd and rcsd strings, the defc string should be used to 
define each character. To print any character on printers covered by terminfo, 
the ASCII code is sent to the printer. This is true for characters in an alternate 
set as well as "normal" characters. Thus the definition of a character includes 
the ASCII code that represents it. In addition, the width of the character in dots 
is given, along with an indication of whether the character should descend 
below the print line (like the lower case letter "g" in most character sets). The 
width of the character in dots also indicates the number of image-data bytes that 
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will follow the defc string. These image-data bytes indicate where in a dot- 
matrix pattern ink should be applied to "draw" the character; the number of 
these bytes and their form are defined below under "Dot-Mapped Graphics". 

It's easiest for the creator of terminfo entries to refer to each character set by 
number; however, these numbers will be meaningless to the application 
developer. The csnm string alleviates this problem by providing names for each 
number. 

When used with a character set number in a call to tparm(), the csnm string will 
produce the equivalent name. These names should be used as a reference only. 
No naming convention is implied, although anyone who creates a terminfo entry 
for a printer should use names consistent with the names found in user docu- 
ments for the printer. Application developers should allow a user to specify a 
character set by number (leaving it up to the user to examine the csnm string to 
determine the correct number), or by name, where the application examines the 
csnm string to determine the corresponding character set number. 

These capabilities are likely to be used only with dot-matrix printers. If they are 
not available, the strings should not be defined. For printers that have manually 
changed print-wheels or font cartridges, the boolean daisy is set. 

Section 2-6: Dot-Matrix Graphics 

Dot-matrix printers typically have the capability of reproducing "raster-graphics" 
images. Three new numeric capabilities and three new string capabilities can 
help a program draw raster-graphics images independent of the type of dot- 
matrix printer or the number of pins or dots the printer can handle at one time. 

Dot-Matrix Graphics 

npins Number of pins, N, in print-head 

spinv Spacing of pins vertically in pins per inch 

spinh Spacing of dots horizontally in dots per inch 

porder Matches software bits to print-head pins 

sbim Start printing bit image graphics, B bits wide 

rbim End printing bit image graphics 

The sbim sring is used with a single argument, B, the width of the image in 
dots. 

The model of dot-matrix or raster-graphics that the terminfo presents is similar to 
the technique used for most dot-matrix printers: Each pass of the printer's 
print-head is assumed to produce a dot-matrix that is N dots high and B dots 
wide. This is typically a wide, squat, rectangle of dots. The height of this 
rectangle in dots will vary from one printer to the next; this is given in the 
npins numeric capability. The size of the rectangle in fractions of an inch will 
also vary; it can be deduced from the spinv and spinh numeric capabilities. 
With these three values an application can divide a complete raster-graphics 
image into several horizontal strips, perhaps interpolating to account for dif- 
ferent dot spacing vertically and horizontally. 

The sbim and rbim strings are used to start and end a dot-matrix image, respec- 
tively. The sbim string is used with a single argument that gives the width of 
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the dot-matrix in dots. A sequence of "image-data bytes" are sent to the printer 
after the sbim string and before the rbim string. The number of bytes is an 
integral multiple of the width of the dot-matrix; the multiple and the form of 
each byte is determined by the porder string as described below. 

The porder string is a comma separated list of pin numbers; the position of each 
pin number in the list corresponds to a bit in a data byte. The pins are num- 
bered consecutively from 1 to npins, with 1 being the top pin. Note that the 
term "pin" is used loosely here; "ink-jet" dot-matrix printers don't have pins, 
but can be considered to have an equivalent method of applying a single dot of 
ink to paper. The bit positions in porder are in groups of 8, with the first posi- 
tion in each group the most significant bit and the last position the least signifi- 
cant bit. 

The "image-data bytes" are to be computed from the dot-matrix image, mapping 
vertical dot positions in each print-head pass into eight-bit bytes, using a 1 bit 
where ink should be applied and where no ink should be applied. If a posi- 
tion is skipped in porder, a bit is used. There must be a multiple of 8 bit posi- 
tions used or skipped in porder; if not, bits are used to fill the last byte in the 
least significant bits. 

Section 2-7: Effect of Changing Printing Resolution 

If the control sequences to change the character pitch or the line pitch are used, 
the pin or dot spacing may change: 

Dot-Matrix Graphics 
Changing the Character/Line Pitches 
cpi Change character pitch 
cpix If set, cpi changes spinh 

Ipi Change line pitch 

Ipix If set, Ipi changes spinv 

Programs that use cpi or Ipi should recalculate the dot spacing: 

Dot-Matrix Graphics 
Effects of Changing the Character/Line Pitches 
Before After 



Using cpi with cpix clear: 

spinh ' spinh 

Using cpi with cpix set: 

spinh ' spinh=spinh' 

orhi' 

Using Ipi with Ipix clear: 

spinv ' spinv 

Using Ipi with Ipix set: 

spinv ' spinv=spinv'~~ 

orhi' 
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Using chr: 
spinh ' 



spinh 



Using cvr: 
spinv ' 



spinv 



orhi' and orhi are the values of the horizontal resolution in steps per inch, 
before using cpi and after using cpi, respectively. Likewise, orvi' and orvi are 
the values of the vertical resolution in steps per inch, before using Ipi and after 
using Ipi, respectively. Thus, the changes in the dots per inch for dot-matrix 
graphics follow the changes in steps per inch for printer resolution. 

Section 2-8: Print Quality 

Many dot-matrix printers can alter the dot spacing of printed text to produce 
near "letter quality" printing or "draft quality" printing. Usually it is important 
to be able to choose one or the other because the rate of printing generally falls 
off as the quality improves. There are three new strings used to describe these 
capabilities. 



The capabilities are listed in decreasing levels of quality. If a printer doesn't 
have all three levels, one or two of the strings should be left blank as appropri- 
ate. 

Section 2-9: Printing Rate and Buffer Size 

Because there is no standard protocol that can be used to keep a program syn- 
chronized with a printer, and because modern printers can buffer data before 
printing it, a program generally cannot determine at any time what has been 
printed. Two new numeric capabilities can help a program estimate what has 
been printed. 



ops is the nominal or average rate at which the printer prints characters; if this 
value is not given, the rate should be estimated at one-tenth the prevailing baud 
rate, bufsz is the maximum number of subsequent characters buffered before 
the guaranteed printing of an earlier character, assuming proper flow control has 
been used. If this value is not given it is assumed that the printer does not 
buffer characters, but prints them as they are received. 

As an example, if a printer has a 1000-character buffer, then sending the letter 
"a" followed by 1000 additional characters is guaranteed to cause the letter "a" 
to print. If the same printer prints at the rate of 100 characters per second, then 
it should take 10 seconds to print all the characters in the buffer, less if the 



Print Quality 



snlq Set near-letter quality print 
snrmq Set normal quality print 
sdrfq Set draft quality print 



Print Rate/Buffer Size 



cps Nominal print rate in characters per second 
bufsz Buffer capacity in characters 
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buffer is not full. By keeping track of the characters sent to a printer, and know- 
ing the print rate and buffer size, a program can synchronize itself with the 
printer. 

Note that most printer manufacturers advertise the maximum print rate, not the 
nominal print rate. A good way to get a value to put in for ops is to generate a 
few pages of text, count the number of printable characters, then see how long it 
takes to print the text. 

Applications that use these values should recognize the variability in the print 
rate. Straight text, in short lines, with no embedded control sequences will 
probably print at close to the advertised print rate and probably faster than the 
rate in cps. Graphics data with a lot of control sequences, or very long lines of 
text, will print at well below the advertised rate and below the rate in cps. If 
the application is using cps to decide how long it should take a printer to print a 
block of text, the application should pad the estimate. If the application is using 
cps to decide how much text has already been printed, it should shrink the esti- 
mate. The application will thus err in favor of the user, who wants, above all, to 
see all the output in its correct place. 

FILES 

/usr/lib/terminfo/?/* compiled terminal description database 
/usr/lib/.COREterm/?/* subset of compiled terminal description database 
/usr/lib/tabset/* tab settings for some terminals, in a format appropri- 

ate to be output to the terminal (escape sequences 
that set margins and tabs) 

SEE ALSO 

curses(3X), printf(3S), profile(4). 

tput(l), vi(l), captoinfo(lM), infocmp(lM), tic(lM), term(5), tty(7) in the 
User/System Administrator's Reference Manual. 

Chapter 10 of the Programmer's Guide, 

WARNING 

As described in the "Tabs and Initialization" section above, a terminal's initiali- 
zation strings, isl, is2, and is3, if defined, must be output before a curses (3X) 
program is run. An available mechanism for outputting such strings is tput init 
[see tput{l) and profile(4:)]. 

If a null character (\0) is encountered in a string, the null and all characters after 
it are lost. Therefore it is not possible to code a null character (\0) and send it 
to a device (either terminal or printer). The suggestion of sending a \0200, 
where a \0 (null) is needed can succeed only if the device (terminal or printer) 
ignores the eighth bit. For example, because all eight bits are used in the stan- 
dard international ASCII character set, devices that adhere to this standard will 
treat \0200 differently from \0. 

Tampering with entries in /usr/lib/.COREterm/?/* or /usr/lib/terminfo/?/* (for 
example, changing or removing an entry) can affect programs such as vi{l) that 
expect the entry to be present and correct. In particular, removing the descrip- 
tion for the " dumb " terminal will cause unexpected problems. 
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NOTE 

The termcap database (from earlier releases of UNIX System V) may not be sup- 
plied in future releases. 
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NAME 

timezone - set default system time zone 

SYNOPSIS 

/etc/TIMEZONE 

DESCRIPTION 

This file sets and exports the time zone environmental variable TZ. 

This file is " dotted " into other files that must know the time zone. 

The syntax of TZ can be described as follows: 

TZ zone 

I zone signed^time 
I zone signed— time zone 
I zone signed— time zone dst 
letter letter letter 
sign time 
I time 
hour 

I hour : minute 
I hour : minute : second 
signed— time 

I signed— time ; dst— date , dst— date 
I ; dst— date , dst— date 
julian 

I julian / time 
a\A\b\B\...\z\Z 
00\01\ ... I 23 
159 
159 
...I 366 



zone 

signed— time 
time 



dst 



dst— date 



00 I 01 I ... 

00 I 01 I ... 

001 I 002 I 
-1 + 



letter 
hour 
minute 

second -> 
julian 
sign 

EXAMPLES 

The contents of /etc/TIMEZONE corresponding to the simple example 
below could be 

# Time Zone 
TZ=EST5EDT 
export TZ 

A simple setting for New Jersey could be 
TZ=EST5EDT 

where EST is the abbreviation for the main time zone, 5 is the difference, in 
hours, between GMT (Greenwich Mean Time) and the main time zone, and 
EDT is the abbreviation for the alternate time zone. 

The most complex representation of the same setting, for the year 1986, is 

TZ= " EST5:00:00EDT4:00:00;117/2:00:00,299/2:00:00 " 

where EST is the abbreviation for the main time zone, 5:00:00 is the differ- 
ence, in hours, minutes, and seconds between GMT and the main time zone. 
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EDT is the abbreviation for the alternate time zone, 4:00:00 is the difference, 
in hours, minutes, and seconds between GMT and the alternate time zone, 
117 is the number of the day of the year (Julian day) when the alternate 
time zone will take effect, 2:00:00 is the number of hours, minutes, and 
seconds past midnight when the alternate time zone will take effect, 299 is 
the number of the day of the year when the alternate time zone will end, 
and 2:00:00 is the number of hours, minutes, and seconds past midnight 
when the alternate time zone will end. 

A southern hemisphere setting such as the Cook Islands could be 

TZ= " KDT9:30KSTl0:00;64/5:00,303/20:00 " 

This setting means that KDT is the abbreviation for the main time zone, KST 
is the abbreviation for the alternate time zone, KST is 9 hours and 30 
minutes later than GMT, KDT is 10 hours later than GMT, the starting date of 
KDT is the 64th day at 5 AM, and the ending date of KDT is the 303rd day at 
8 PM. 

Starting and ending times are relative to the alternate time zone. If the 
alternate time zone start and end dates and the time are not provided, the 
days for the United States that year will be used and the time will be 2 AM. 
If the start and end dates are provided but the time is not provided, the 
time will be midnight. 

Note that in most installations, TZ is set to the correct value by default 
when the user logs on, via the local /etc/profile file [see profile{4)]. 

SEE ALSO 

ctime(3C), profile(4), environ(5). 

rc2(lM) in the User's /System Administrator's Reference Manual. 

NOTES 

When the longer format is used, the TZ variable must be surrounded by 
double quotes as shown. 

The system administrator must change the Julian start and end days annu- 
ally if the longer form of the TZ variable is used. 

Setting the time during the interval of change from the main time zone to 
the alternate time zone or vice versa can produce unpredictable results. 
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NAME 

unistd - file header for symbolic constants 

SYNOPSIS 

#include <unistd.h> 

DESCRIPTION 

The header file <unistd.h> lists the symbolic constants and structures not 
already defined or declared in some other header file. 



/* Symbolic constants for the "access" routine: */ 



#define R_OK 4 

#define W_OK 2 

#define X_OK 1 

#define F_OK 

#define F_ULOCK 

#define F_LOCK 1 

#define F_TLOCK 2 

#define F_TEST 3 



/*Test for Read permission */ 
/*Test for Write permission */ 
/*Test for eXecute permission */ 
/*Test for existence of File */ 

/♦Unlock a previously locked region */ 
/*Lock a region for exclusive use */ 
/*Test and lock a region for exclusive use */ 
/♦Test a region for other processes locks ♦/ 



/♦Symbolic constants for the "Iseek" routine: ♦/ 



#define SEEK_SET 
#define SEEK_CUR 
#define SEEKJEND 

/♦Path names:^/ 

#define GF_PATH 
#define PF_PATH 



/♦ Set file pointer to "offset" ♦/ 

1 /♦ Set file pointer to current plus "offset" ♦/ 

2 /♦ Set file pointer to EOF plus "offset" ♦/ 



"/etc/group" /♦Path name of the group file ♦/ 
"/etc/passwd" /♦Path name of the passwd file ♦/ 
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NAME 

utmp, wtmp - utmp and wtmp entry formats 

SYNOPSIS 

#include <sys/types.h> 

#include <utmp.h> 

DESCRIPTION 

These files, which hold user and accounting information for such commands 
as who(l), write(l), and login{l), have the following structure as defined by 
<utmp.h>: 



#define 
#define 
#define 

stiruct 



UIMP_FIIjE "/etcActnp" 
WIMP_FIIiE "/etcArtup" 
ut 



UtiDp { 

char 
char 
char 
short 
short 
struct 



ut_user[8] ; /* User login name ♦/ 

iit_id[4]; /* /etc/inittab id (usually line #) */ 
ut_line[12]; /* device name (oooisole, luxx) */ 

ut__pid; /* process id */ 

utjtype; /* type of entry */ 
exit_status { 

short ejterttdnatian; /* Process termination status */ 

short ejsacLt; /* Process exit status */ 
} ut_exit; /♦ T5ie exit status of a process 

/♦marked as eeadjewxess. ♦/ 
time_t ut_time; /* time entry was made */ 



*/ 


1 



}; 

/* Definitions for utjtype 
#define EMPTY 

RDNJiVL 
BOOTjnWE 2 
QLD_TIME 3 
NEWJEEME 4 
INITPROCESS 
IiOGIN_FROCESS 
USERJRDCESS 
DEAD_PRDCESS 8 
AOO0UNnNG9 

UTMAXTYPE AaxJUNTiNG /* Largest legal value of ut_type ♦/ 



/* Process spavmed by "init" */ 
/* A "getty" process waiting for login */ 
/* A user process */ 



#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 

/* Special strings or fornats used in the "ut_line" field v*ien 

/* accounting for soraething other than a process */ 

/♦ No string for the ut_line field can be more than 11 chars + 

/» a NULL in length */ 

#define KUNLVL_M9G "run-level %c» 

#define B0OTJ©G "system boot" 

#define 0fnME_M9G "old time" 

#define NTIME_MSG "new time" 



*/ 



FILES 



/etc/utmp 
/etc/ wtmp 
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SEE ALSO 

getut(3C). 

login(l), who(l), write(l) in the Usefs/System Administrators Reference 
Manual 
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NAME 

intro - introduction to miscellany 
DESCRIPTION 

This section describes miscellaneous facilities such as macro packages, char- 
acter set tables, etc. 
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NAME 

ascii - map of ASCII character set 
DESCRIPTION 

ascii is a map of the ASCII character set. It lists octal, hexadecimal, and 
decimal equivalents of each character. The ascii map contains the following 
tables: 

Octal ASCII 



000 


nul 


1001 


soh 


1002 stx 


1003 etx 


1004 eot 


1005 enq 


1006 ack 


1007 bel 


010 


bs 


1011 


ht 


!012 nl 


1013 vt 


1014 np 


1015 cr 


1016 so 


1017 si 


020 


die 


1021 


del 


1022 dc2 


1023 dc3 


!024 dc4 


1025 nak 


!026 syn 


1027 etb 


030 


can 


1031 


em 


1032 sub 


1033 esc 


1034 fs 


1035 gs 


1036 rs 


1037 us 


040 


sp 


1041 


I 


1042 " 


1043 # 


1044 $ 


1045 % 


1046 & 


1047 / 


050 


( 


1051 


) 


1052 * 


1053 + 


!054, 


!055 - 


1056. 


1057/ 


060 





1061 


1 


1062 2 


1063 3 


1064 4 


1065 5 


1066 6 


1067 7 


070 


8 


1071 


9 


1072 : 


1073 ; 


1074 < 


1075 = 


1076 > 


1077? 


100 


@ 


1101 


A 


1102 B 


1103 C 


1104 D 


1105 E 


1106 F 


1107 G 


110 


H 


1111 


I 


1112 J 


1113 K 


1114 L 


1115 M 


1116 N 


1117 O 


120 


P 


1121 


Q 


1122 R 


1123 S 


1124 T 


1125 U 


1126 V 


1127 W 


130 


X 


1131 


Y 


1132 Z 


1133 [ 


1134 \ 


1135] 


1136 ^ 


1137 _ 


140 


\ 


1141 


a 


1142 b 


1143 c 


1144 d 


1145 e 


1146 f 


1147 g 


150 


h 


1151 


i 


1152 j 


1153 k 


1154 1 


1155 m 


1156 n 


1157 o 


160 


P 


1161 


q 


1162 r 


1163 s 


1164 t 


1165 u 


1166 V 


1167 w 


170 


X 


!171 


y 


1172 z 


1173 { 


!174l 


1175 } 


!176 - 


1177 del 



Hexadecimal ASCII 



00 


nul j 


01 


soh 


I 02 stx 


03 etx 


I 04 eot 


05 enq 


06 ack 


07 bel 


08 


bs 1 


09 


ht 


1 Oa nl 


Ob vt 


1 Oc np 


Oder 


Oe so 


Of si 


10 


die 1 


11 


del 


1 12 dc2 


13 dc3 


1 14 dc4 


15 nak 


16 syn 


17 etb 


18 


can 1 


19 


em 


1 la sub 


lb esc 


1 Ic fs 1 


Id gs 


le rs 


If us 


20 


sp I 


21 


! 


22 " 


23 # 


■24$ 1 


25 % 


26 & 


27/ 


28 


( ! 


29 


) 


2a * 1 


2b + 


2c, 1 


2d- 


2e . 1 


2f/ 


30 


1 


31 


1 


32 2 1 


33 3 


34 4 1 


35 5 


36 6 1 


37 7 


38 


8 1 


39 


9 


3a : 1 


3b; 


3c < j 


3d = 


3e> 1 


3f ? 


40 


@ ! 


41 


A 


42 B 1 


43 C 


44 D j 


45 E 


46 F ! 


47 G 


48 


H 1 


49 


I 


4a J 1 


4b K 


4c L 1 


4dM 


4eN ! 


4f O 


50 


P 1 


51 


Q 


52 R 1 


53 S 


54 T 1 


55 U 


56 V 1 


57 W 


58 


X 1 


59 


Y 


5a Z 1 


5b [ 


5c \ 1 


5d] 


5e ^ 1 


5f _ 


60 


X I 


61 


a 


62 b 1 


63 c 


64 d I 


65 e 


66 f 1 


67 g 


68 


h 1 


69 


i 


6a j I 


6b k 


6c 1 1 


6d m 


6e n 1 


6f o 


70 


P 5 


71 


q 


72 r ! 


73 s 


74 t I 


75 u 1 


76 V 1 


77 w 


78 


X 1 


79 


y 


7a z 1 


7b { 


7c 1 1 


7d } 1 


7e - ! 


7f del 
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Decimal ASCII 

I nul I 1 soh I 2 stx 

i 8bs I 9ht llOnl 

I 16 die I 17 del 1 18 dc2 

I 24 can I 25 em I 26 sub 

I32sp 133 ! 134 " 

140 ( 141 ) !42 * 

148 149 1 150 2 

156 8 157 9 158 : 

164 @ 165 A 166 B 

172 H 173 I 174 J 

180 P 181 Q 182 R 

188 X 189 Y 190 Z 

196 ' 197 a 198 b 

1104 h 1105 i 1106 j 

1112 p 1113 q 1114 r 

1120 X 1121 y 1122 z 

FILES 

/usr/pub/ascii 



I 3 etx 14 eot ! 5 enq 

I 11 vt I 12 np I 13 cr 

I 19 dc3 I 20 dc4 I 21 nak 

I 27 esc I28fs I 29 gs 

135 # 136 $ 137 % 

143 + 144 , 145 - 

151 3 152 4 153 5 

159 ; 160 < 161 = 

167 C 168 D !69 E 

175 K 176 L 177 M 

183 S 184 T 185 U 

191 [ 192 \ 193 ] 

199 c 1100 d 1101 e 

1107 k 1108 1 1109 m 

1115 s 1116 t 1117 u 

1123 { 1124 I 1125 } 
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I 6ack I 7bel I 



1 14 


so 


1 10 SI 1 


122 


syn 


1 23 etb 1 


130 rs 


1 31 us I 


138 


& 


1 39 1 


146 




147 / 1 


154 


6 


155 7 1 


162 


> 


163 ? 1 


1 70 


F 


171 G 1 


1 78 


N 


179 O 1 


!86 


y 


187 W 1 


194 




195 _ 1 


1102 


f 


1103 g 1 


1110 


n 


1111 o 1 


1118 


V 


1119 w ! 


1126 




1127 del 1 
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NAME 

environ - user environment 
DESCRIPTION 

An array of strings called the "environment" is made available by exec (2) 
when a process begins. By convention, these strings have the form 
"name=value". The following names are used by various commands: 

CFTIME The default format string to be used by the date{l) command 
and the ascftime() and cftime() routines [see ctime(3C)]. If 
CFTIME is not set or is null, the default format string specified 
in the /lib /cttime/ LANGUAGE file (if it exists) is used in its 
place [see cftime(^)]. 

CHRCLASS A value that corresponds to a file in /lib/chrclass containing 
character classification and conversion information. This infor- 
mation is used by commands (such as caf(l), ed(l), sorf(l), 
etc.) to classify characters as alphabetic, printable, uppercase, 
etc., and to convert characters to uppercase or lowercase. 

When a program or command begins execution, the tables con- 
taining this information are initialized based on the value of 
CHRCLASS. If CHRCLASS is nonexistent, null, set to a value 
for which no file exists in /lib/chrclass, or errors occur while 
reading the file, the ASCII character set is used. During execu- 
tion, a program or command can change the values in these 
tables by calling the setchrclass() routine. For more detail, see 
ctype{3C). 

These tables are created using the chrtbl{lM) command. 

HOME The name of the user's login directory, set by login(l) from the 
password file [see passwd(4)]. 

LANGUAGE A language for which a printable file by that name exists in 
/lib/cftime. This information is used by commands (such as 
date(l), /s(l), sorf(l), etc.) to print date and time information 
in the language specified. 

If LANGUAGE is nonexistent, null, set to a value for which no 
file exists in /lib/cftime, or errors occur while reading the file, 
the last language requested will be used. (If no language has 
been requested, the language usa— english is assumed.) For a 
description of the content of files in /lib/cftime, see cftime{4:). 

PATH The sequence of directory prefixes that sh{l), time{l), nice(l), 

nohup{l), etc., apply in searching for a file known by an 
incomplete path name. The prefixes are separated by colons 
(:). login{l) sets PATH=:/bin:/usr/bin. (For more detail, see 
the "Execution" section of the sh{l) manual page.) 

TERM The kind of terminal for which output is to be prepared. This 

information is used by commands, such as mm(l) or vi{l), 
which may exploit special capabilities of that terminal. 
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TZ Time zone information. The simplest format is xxxnzzz where 

XXX is the standard local time zone abbreviation, n is the 
difference in hours from GMT (Greenwich Mean Time), and 
zzz is the abbreviation for an alternate time zone (usually the 
daylight-saving local time zone), if any; for example, 

TZ="EST5EDT" 

The most complex format allows you to specify the difference 
in hours of the alternate time zone from GMT and the starting 
day and time and ending day and time for using this alternate 
time zone. For example, in 1985 the complex format 
corresponding to the above simple example is: 

TZ= " EST5:00:00EDT4:00:00;118/2:00:00,300/2:00:00 " 

When the above complex format is used, it must be sur- 
rounded by double quotes. For more details, see ctime{3C) 
and timezone(A), 

Further names may be placed in the environment by the export command 
and "name=value" arguments in sh{l), or by exec{2). It is unwise to con- 
flict with certain shell variables that are frequently exported by .profile files: 
MAIL, PSl, PS2, IFS [see profile{4t)]. 

SEE ALSO 

exec(2), ctime(3C), ctype(3C), cftime(4), passwd(4), profile(4), timezone(4). 

cat(l), date(l), ed(l), env(l), ls(l), login(l), nice(l), nohup(l), sh(l), sort(l), 
time(l), vi(l), chrtbl(lM) in the User's /System Administrator's Reference 
Manual, 

mm(l) in the DOCUMENTER'S WORKBENCH Software Release 2.0 Technical Dis- 
cussion and Reference Manual. 

NOTES 

References to the cftime{4), ctime{3C), and ctype{3C) manual pages refer to 
programming capabilities available beginning with Issue 4.1 of the C Pro- 
gramming Language Utilities. 

Administrators should note the following: if you attempt to set the current 
date to one of the dates that the standard and alternate time zones change 
(for example, the date that daylight time is starting or ending), and you 
attempt to set the time to a time in the interval between the end of standard 
time and the beginning of the alternate time (or the end of the alternate 
time and the beginning of standard time), the results are unpredictable. 
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NAME 

fcntl - file control options 

SYNOPSIS 

#include <fcntl.h> 

DESCRIPTION 

The fcntl (2) function provides for control over open files. This include file 
describes requests and arguments to fcntl and open (2). 

/* Flag values accessible to open(2) and fcntl(2) */ 
/* (The first three can only be set by open) */ 



#define 
#define 
#define 
#define 
#define 



0_RDONLY 
0_WRONLY 
0_RDWR 
0_NDELAY 
0_APPEND 



#define 0__SYNC 




1 
2 

04 

010 

020 



/* Non-blocking I/O */ 

/* append (writes guaranteed at the end) */ 

/* synchronous write option */ 



/* Flag values accessible only to open(2) */ 



#define 0--CREAT 00400 

#define 0_TRUNC 01000 

#define 0_£XCL 02000 

/* fcntl(2) requests */ 

#define F_DUPFD 

#define F_GETFD 1 

#define F_SETFD 2 

#define F_GETFL 3 

#define F_SETFL 4 

#define F_GETLK 5 

#define F_SETLK 6 

#define F_SETLKW 7 

#define F-_CHKFL 8 



/* open with file create (uses third open arg)*/ 
/* open with truncation */ 
/* exclusive open */ 



/* Duplicate fildes */ 

/* Get fildes flags */ 

/* Set fildes flags */ 

/* Get file flags */ 

/* Set file flags */ 

/* Get file lock */ 

/* Set file lock */ 

/* Set file lock and wait */ 

/* Check legality of file flag changes */ 



/* file segment locking control structure */ 
struct flock { 

short Ltype; 

short Lwhence; 

long Lstart; 



long LJen; 
short l_sysid; 
short l_pid; 



/* if then until EOF */ 

/* returned with F_GETLK*/ 

/* returned with F_GETLK*/ 



/* file segment locking types */ 
#define F_RDLCK 01 /* Read lock */ 
#define F_WRLCK 02 /* Write lock */ 
#define F_UNLCK 03 /* Remove locks */ 

SEE ALSO 

fcntl(2), open(2). 
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NAME 

jagent - host control of windowing terminal 

SYNOPSIS 

#include <sy8/jioctl.h> 

ioctl (cntlfd, JAGENT, &arg) 

int cntlfd 

struct bagent arg 

DESCRIPTION 

The ioctl{2) system call, when performed on an xt{7) device with the 
JAGENT request, allows a host program to send information to a windowing 
terminal. 

ioctl has three arguments: 

cntlfd the xt(7) control channel file descriptor 

JAGENT the xt(7) ioctl{2) request to invoke a windowing terminal agent 
routine, 

arg the address of a bagent structure, defined in <sys/jioctl.h> as 

follows: 

struct bagent { 

long size; /♦ size of src in & dest out */ 
char ♦src; /* the source byte string */ 
char *dest; /* the destination byte string */ 

}; 

The src pointer must be initialized to point to a byte string which is sent to 
the windowing terminal. See layers(5) for a list of JAGENT strings recog- 
nized by windowing terminals. Likewise, the dest pointer must be initial- 
ized to the address of a buffer to receive a byte string returned by the termi- 
nal. When ioctl(2) is called, the size argument must be set to the length of 
the src string. Upon return, size is set by ioctl{2) to the length of the desti- 
nation byte string, dest, 

SEE ALSO 

ioctl(2), libwindows(3X), layers(5). 

xt(7) in the User's /System Administrator's Reference Manual 
DIAGNOSTICS 

Upon successful completion, the size of the destination byte string is 
returned. If an error occurs, -1 is returned. 
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NAME 

layers - protocol used between host and windowing terminal under 
layers {1) 

SYNOPSIS 

#include <sys/jioctLh> 

DESCRIPTION 

layers are asynchronous windows supported by the operating system in a 
windowing terminal. Communication between the UNIX system processes 
and terminal processes under layers{l) occurs via multiplexed channels 
managed by the respective operating systems using a protocol as specified 
in xtproto(5). 

The contents of packets transferring data between a UNIX system process 
and a layer are asymmetric. Data sent from the UNIX system to a particular 
terminal process is undifferentiated and it is up to the terminal process to 
interpret the contents of packets. 

Control information for terminal processes is sent via channel 0. Process 
in the windowing terminal performs the designated functions on behalf of 
the process connected to the designated channel. These packets take the 
form: 



command, channel 

except for timeout and jagent information which take the form 

command, data... 

The commands are the bottom eight bits extracted from the following 
ioctl(2) codes: 

JBOOT Prepare to load a new terminal program into the designated 
layer. 

JTERM Kill the downloaded layer program and restore the default win- 
dow program. 

JTIMO Set the timeout parameters for the protocol. The data consist of 
two bytes: the value of the receive timeout in seconds and the 
value of the transmit timeout in seconds. 

JTIMOM Set the timeout parameters for the protocol. The data consist of 
four bytes in two groups: the value of the receive timeout in 
milliseconds (the low eight bits followed by the high eight bits) 
and the value of the transmit timeout (in the same format). 

JZOMBOOT 

Like JBOOT, but do not execute the program after loading. 

JAGENT Send a source byte string to the terminal agent routine and wait 
for a reply byte string to be returned. 

The data are from a bagent structure [see jagent(5)] and consist of 
a one-byte size field followed by a two-byte agent command 
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code and parameters. Two-byte integers transmitted as part of 
an agent command are sent with the high-order byte first. The 
response from the terminal is generally identical to the command 
packet, with the two command bytes replaced by the return 
code: for success, -1 for failure. Note that the routines in the 
libwindows{3X) library all send parameters in an agentrect struc- 
ture. The agent command codes and their parameters are as fol- 
lows: 



A-_NEWLAYER 

A--CURRENT 
A-DELETE 
A_TOP 
A_BOTTOM 
A_MOVE 

A__RESHAPE 

A--NEW 

A_EXIT 

A_ROMVERSION 



followed by a two-byte channel number and a 
rectangle structure (four two-byte coordinates). 

followed by a two-byte channel number. 

followed by a two-byte channel number. 

followed by a two-byte channel number. 

followed by a two-byte channel number. 

followed by a two-byte channel number and a 
point to move to (two two-byte coordinates). 

followed by a two-byte channel number and 
the new rectangle (four two-byte coordinates). 

followed by a two-byte channel number and a 
rectangle structure (four two-byte coordinates). 

no parameters needed. 

no parameters needed. The response packet 
contains the size byte, two-byte return code, 
two unused bytes, and the parameter part of 
the terminal id string (e.g., "8;7;3"). 



Packets from the windowing terminal to the UNIX system all take the fol- 
lowing form: 

command, data... 
The single-byte commands are as follows: 

C_SENDCHAR Send the next byte to the UNIX system process. 

C—NEW Create a new UNIX system process group for this 

layer. Remember the window size parameters for 
this layer. The data for this command is in the 
form described by the jwinsize structure. The size 
of the window is specified by two 2-byte integers, 
sent low byte first. 
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C_UNBLK 

C_DELETE 

C_EXIT 

C_DEFUNCT 

C__SENDNCHARS 
C_RESHAPE 



Unblock transmission to this layer. There is no 
data for this command. 

Delete the UNIX system process group attached to 
this layer. There is no data for this command. 

Exit. Kill all UNIX system process groups associated 
with this terminal and terminate the session. There 
is no data for this command. 

Layer program has died, send a terminate signal to 
the UNIX system process groups associated with this 
terminal. There is no data for this command. 

The rest of the data are characters to be passed to 
the UNIX system process. 

The layer has been reshaped. Change the window 
size parameters for this layer. The data takes the 
same form as for the C-_NEW command. 



SEE ALSO 

libwindows(3X), jagent(5), xtproto(5). 

layers(l), xt(7) in the User's /System Administrator's Reference Manual 
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NAME 

math - math functions and constants 

SYNOPSIS 

#include <math.h> 

DESCRIPTION 

This file contains declarations of all the functions in the Math Library 
(described in Section 3M), as well as various functions in the C Library 
(Section 3C) that return floating-point values. 

It defines the structure and constants used by the matherr{3M) error- 
handling mechanisms, including the following constant used as an error- 
return value: 

HUGE The maximum value of a single-precision floating- 

point number. 

The following mathematical constants are defined for user convenience: 

M_E The base of natural logarithms (e). 

M_LOG2E The base-2 logarithm of e. 

M_LOG10E The base-10 logarithm of e, 

M_LN2 The natural logarithm of 2. 

M_LN10 The natural logarithm of 10. 

M PT TT, the ratio of the circumference of a circle to its 

diameter. 

M_PI_2 ir/2. 

M_PI_4 7r/4. 

M_1_-PI I/tt. 

M_2_PI 2/7r. 

M_2_SQRTPI 2/V7r. 

M_SQRT2 The positive square root of 2. 

M_SQRT1_2 The positive square root of 1/2. 

For the definitions of various machine-dependent "constants," see the 
description of the <values.h> header file. 

SEE ALSO 

intro(3), matherr(3M), values(5). 
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NAME 

prof - profile within a function 

SYNOPSIS 

#defme MARK 
#include <prof.h> 

void MARK (name) 

DESCRIPTION 

MARK will introduce a mark called name that will be treated the same as a 
function entry point. Execution of the mark will add to a counter for that 
mark, and program-counter time spent will be accounted to the immediately 
preceding mark or to the function if there are no preceding marks within 
the active function. 

Name may be any valid C identifier. Each name in a single compilation 
must be unique, but may be the same as any ordinary program symbol. 

For marks to be effective, the s)aiibol MARK must be defined before the 
header file <prof.h> is included. This may be defined by a preprocessor 
directive as in the synopsis or by a command line argument, i.e: 

cc -p -DMARK foo.c 

If MARK is not defined, the MARK{name) statements may be left in the 
source files containing them and will be ignored. 

EXAMPLE 

In this example, marks can be used to determine how much time is spent in 
each loop. Unless this example is compiled with MARK defined on the com- 
mand line, the marks are ignored. 

#include <prof.h> 
foo( ) 

{ 

int i, j; 



MARK(loopl); 

for (i = 0; i < 2000; i++) { 
} 

MARK(loop2); 

for (j = 0; j < 2000; j++) { 



SEE ALSO 

prof(l), profil(2), monitor(3C). 
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NAME 

regexp - regular expression compile and match routines 

SYNOPSIS 

#de£ine INIT <declarations> 
#define GETCO <getc code> 
#define PEEKCO <peekc code> 
#define UNGETC(c) <ungetc code> 
#define RETURN(pointer) <retum code> 
#define ERROR(val) <error code> 

#include <regexp.h> 

char ^compile (instring, expbuf, endbuf, eof) 
char I'instring, *expbuf, *endbuf; 
int eof; 

int step (string, expbuf) 
char lustring, *expbuf; 

extern char *locl, *loc2, *locs; 

extern int circf, sed, nbra; 

DESCRIPTION 

This page describes general-purpose, regular expression matching routines 
in the form of ed(l), defined in <regexp.h> . Programs such as ed{l), 
sed{l), grep{l), bs{l), expr{l), etc., which perform regular expression match- 
ing use this source file. In this way, only this file need be changed to main- 
tain regular expression compatibility. 

The interface to this file is complex. Programs that include this file must 
have the following five macros declared before the "#include <regexp.h>" 
statement. These macros are used by the compile routine. 

GETC() Return the value of the next character in the regular 

expression pattern. Successive calls to GETC() should 
return successive characters of the regular expression. 

PEEKC() Return the next character in the regular expression. 

Successive calls to PEEKC() should return the same 
character [which should also be the next character 
returned by GETC()]. 

UNGETC(c) Cause the argument c to be returned by the next call 

to GETC( ) [and PEEKC( )]. No more that one character 
of pushback is ever needed, and this character is 
guaranteed to be the last character read by GETC(). 
The value of the macro UNGETC(c) is always ignored. 

KETlJRN{pointer) This macro is used on normal exit of the compile rou- 
tine. The value of the argument pointer is a pointer 
to the character after the last character of the com- 
piled regular expression. This is useful to programs 
which have memory allocation to manage. 
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ERROR(i;fl/) 



This is the abnormal return from the compile routine. 
The argument val is an error number (see table below 
for meanings). This call should never return. 



ERROR 



MEANING 



11 
16 
25 
36 
41 
42 
43 
44 
45 
46 
49 
50 



Range endpoint too large. 
Bad number. 
"\digit" out of range. 
Illegal or missing delimiter. 
No remembered search string. 
\( \) imbalance. 
Too many \(. 

More than 2 numbers given in \{ \}. 
} expected after \. 

First number exceeds second in \{ \}. 
[ ] imbalance. 

Regular expression overflow. 



The syntax of the compile routine is as follows: 
compile(instring, expbuf, endbuf, eof) 

The first parameter instring is never used explicitly by the compile routine 
but is useful for programs that pass down different pointers to input charac- 
ters. It is sometimes used in the INIT declaration (see below). Programs 
which call functions to input characters or have characters in an external 
array can pass down a value of ((char *) 0) for this parameter. 

The next parameter expbuf is a character pointer. It points to the place 
where the compiled regular expression will be placed. 

The parameter endbuf is one more than the highest address where the com- 
piled regular expression may be placed. If the compiled expression cannot 
fit in (endbuf-expbuf) bytes, a call to ERROR(50) is made. 

The parameter eof is the character which marks the end of the regular 
expression. For example, in ed{l), this character is usually a /. 

Each program that includes this file must have a #define statement for INIT. 
This definition will be placed right after the declaration for the function 
compile and the opening curly brace ({). It is used for dependent declara- 
tions and initializations. Most often it is used to set a register variable to 
point to the beginning of the regular expression so that this register variable 
can be used in the declarations for GETC(), PEEKC() and UNGETC(). Other- 
wise it can be used to declare external variables that might be used by 
GETC(), PEEKCO and UNGETC(). See the example below of the declarations 
taken from grep(l). 

There are other functions in this file which perform actual regular expres- 
sion matching, one of which is the function step. The call to step is as fol- 
lows: 

step(string, expbuf) 
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The first parameter to step is a pointer to a string of characters to be 
checked for a match. This string should be null-terminated. 

The second parameter expbuf is the compiled regular expression which was 
obtained by a call of the ifunction compile. 

The function step returns non-zero if the given string matches the regular 
expression, and zero if the expressions do not match. If there is a match, 
two external character pointers are set as a side effect to the call to step. 
The variable set in step is loci. This is a pointer to the first character that 
matched the regular expression. The variable /oc2, which is set by the func- 
tion advance, points to the character after the last character that matches the 
regular expression. Thus if the regular expression matches the entire line, 
loci will point to the first character of string and loci will point to the null 
at the end of string. 

Step uses the external variable circf which is set by compile if the regular 
expression begins with . If this is set, then step will try to match the regu- 
lar expression to the beginning of the string only. If more than one regular 
expression is to be compiled before the first is executed, the value of circf 
should be saved for each compiled expression, and circf should be set to 
that saved value before each call to step . 

The function advance is called from step with the same arguments as step. 
The purpose of step is to step through the string argument and call advance 
until advance returns non-zero indicating a match or until the end of string 
is reached. If one wants to constrain string to the beginning of the line in 
all cases, step need not be called; simply call advance . 

When advance encounters a * or \{ \} sequence in the regular expression, it 
will advance its pointer to the string to be matched as far as possible and 
will recursively call itself trying to match the rest of the string to the rest of 
the regular expression. As long as there is no match, advance will back up 
along the string until it finds a match or reaches the point in the string that 
initially matched the * or \{ \}. It is sometimes desirable to stop this back- 
ing up before the initial point in the string is reached. If the external char- 
acter pointer Iocs is equal to the point in the string at sometime during the 
backing up process, advance will break out of the loop that backs up and 
will return zero. This is used by ed{\) and sed{\) for substitutions done glo- 
bally (not just the first occurrence, but the whole line) so, for example, 
expressions like s/y*//g do not loop forever. 

The additional external variables sed and nhra are used for special purposes. 

EXAMPLES 

The following is an 
look from grep{\): 

#define INIT 
#define GETC() 
#define PEEKC() 
#define UNGETC(c) 
#define RETURN(c) 
#define ERROR(c) 
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example of how the regular expression macros and calls 

register char *sp = instring; 

(*sp++) 

(*sp) 

(-sp) 

return; 

regerrO 
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#include <regexp.h> 

(void) compile(*argv, expbuf, &expbuf[ESIZE], '\0'); 

if (step(linebuf, expbuf)) 

succeed( ); 

SEE ALSO 

ed(l), expr(l), grep(l), regcmp(3x), sed(l) in the User's/System 
Administratofs Reference Manual. 
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NAME 

Stat - data returned by stat system call 

SYNOPSIS 

#include <sys/t3rpes.h> 
#include <sys/stat.h> 

DESCRIPTION 

The system calls stat and fstat return data whose structure is defined by this 
include file. The encoding of the field st-.mode is defined in this file also. 

Structure of the result of stat 



stat 




dev_t 


st_dev; 


ushort 


st_ino; 


ushort 


st_mode; 


short 


st_nlink; 


ushort 


sL_uid; 


ushort 


st_gid; 


dev_t 


st_rdev; 


off_t 


st__size; 


time_t 


st__atime; 


time__t 


st_mtime; 


time_t 


st_ctime; 



}; 



#define S_IFMT 0170000 /* type of file */ 

#define S_IFDIR 0040000 /* directory */ 

#define S_IFCHR 0020000 /* character special ♦/ 

#define S_IFBLK 0060000 /* block special */ 

#define S_IFREG 0100000 /* regular */ 

#define S-JFIFO 0010000 /* fifo */ 

#define S_ISUID 04000 /* set user id on execution */ 

#define S-ISGID 02000 /* set group id on execution */ 

#define S_ISVTX 01000 /* save swapped text even after use */ 

#define S_IREAD 00400 /* read permission, owner */ 

#define S_IWRITE 00200 /* write permission, owner */ 

#define S_IEXEC 00100 /* execute/search permission, owner */ 

#define S_ENFMT S_ISGID /* record locking enforcement flag */ 

#define S_IRWXU 00700 /* read, write, execute: owner */ 

#define S_JRUSR 00400 /* read permission: owner */ 

#define S_IWUSR 00200 /* write permission: owner */ 

#define S_IXUSR 00100 /* execute permission: owner */ 

#define S_IRWXG 00070 /* read, write, execute: group */ 

#define S_IRGRP 00040 /* read permission: group */ 

#define S_IWGRP 00020 /* write permission: group */ 

#define S_IXGRP 00010 /* execute permission: group */ 

#define S_IRWXO 00007 /* read, write, execute: other */ 

#define S_JROTH 00004 /* read permission: other */ 
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#define S_IWOTH 00002 /* write permission: other */ 
#define S_JXOTH 00001 /* execute permission: other */ 

SEE ALSO 

stat(2), types(5). 
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NAME 

term - conventional names for terminals 
DESCRIPTION 

These names are used by certain commands [e.g., man{l\ tabs{l), tput(l), 
vi{l) and curses{3X)] and are maintained as part of the shell environment in 
the environment variable TERM [see sh{l), profile{4:), and environ{5)]. 

Entries in terminfo{4) source files consist of a number of comma-separated 
fields. [To obtain the source description for a terminal, use the -I option of 
infocmp (IM).] White space after each comma is ignored. The first line of 
each terminal description in the terminfo(^) data base gives the names by 
which terminfo{4) knows the terminal, separated by bar ( ! ) characters. The 
first name given is the most common abbreviation for the terminal [this is 
the one to use to set the environment variable TERMINFO in 
$HOME/.profile; see profile{4)], the last name given should be a long name 
fully identifying the terminal, and all others are understood as s)monyms for 
the terminal name. All names but the last should contain no blanks and 
must be unique in the first 14 characters; the last name may contain blanks 
for readability. 

Terminal names (except for the last, verbose entry) should be chosen using 
the following conventions. The particular piece of hardware making up the 
terminal should have a root name chosen. For example, for the AT&T 4425 
terminal, the root name is att4425. This name should not contain hyphens, 
except that synonyms may be chosen that do not conflict with other names. 
Up to 8 characters, chosen from [a-zO-9], make up a basic temunal name. 
Names should generally be based on original vendors, rather than local dis- 
tributors. A terminal acquired from one vendor should not have more than 
one distinct basic name. Terminal sub-models, operational modes that the 
hardware can be in, or user preferences, should be indicated by appending a 
hyphen and an indicator of the mode. Thus, an AT&T 4425 terminal in 132 
column mode would be att4425-w. The following suffixes should be used 
where possible: 



Suffix 


Meaning 


Example 


-w 


Wide mode (more than 80 columns) 


att4425-w 


-am 


With auto, margins (usually default) 


vtlOO-am 


-nam 


Without automatic margins 


vtlOO-nam 


-n 


Number of lines on the screen 


aaa-60 


-na 


No arrow keys (leave them in local) 


clOO-na 


-np 


Number of pages of memory 


cl00-4p 


-rv 


Reverse video 


att4415-rv 



To avoid conflicts with the naming conventions used in describing the dif- 
ferent modes of a terminal (e.g., -w), it is recommended that a terminal's 
root name not contain hyphens. Further, it is good practice to make all ter- 
minal names used in the tenninfo{4) data base unique. Terminal entries that 
are present only for inclusion in other entries via the use= facilities should 
have a in their name, as in 4415+nl, 

Some of the known terminal names may include the following (for a com- 
plete list, type: Is -C /usr/lib/terminfo/?): 
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2621,hp2621 

2631 

2631-c 

2631-e 

2640,hp2640 

2645,hp2645 

3270 

33,tty33 

35,tty35 

37,tty37 

4000a 

4014,tek4014 

40,tty40 

43,tty43 

4410,5410 

4410-nfk,5410-nfk 

4410-nsl,5410-nsl 

4410-w,5410-w 

4410vl,5410vl 

4410vl-w,5410vl-w 

4415,5420 

4415-nl,5420-nl 

4415-rv,5420-rv 

4415-rv-nl,5420-rv-nl 

4415-w,5420-w 

4415-w-nl,5420-w-nl 

44 15-w-rv,5420-w-rv 

44 1 5-w-rv-nl,5420-w-rv-nl 

4418,5418 

4418-w,5418-w 

4420 

4424 

4424- 2 
4425,5425 

4425- fk,5425-fk 
4425-nl,5425-nl 

4425-w,5425-w 
4425-w-fk,5425-w-fk 

4425-nl-w,5425-nl-w 

4426 
450 

450-12 
500,att500 
510,510a 
513bct,att513 



Hewlett-Packard 2621 series 

Hewlett-Packard 2631 line printer 

Hewlett-Packard 2631 line printer - compressed mode 

Hewlett-Packard 2631 line printer - expanded mode 

Hewlett-Packard 2640 series 

Hewlett-Packard 2645 series 

IBM Model 3270 

AT&T TELETYPE Model 33 KSR 
AT&T TELETYPE Model 35 KSR 
AT&T TELETYPE Model 37 KSR 
Trendata 4000a 
TEKTRONIX 4014 

AT&T TELETYPE Dataspeed 40/2 
AT&T TELETYPE Model 43 KSR 

AT&T 4410/5410 terminal in 80-column mode - version 2 
AT&T 4410/5410 without function keys - version 1 
AT&T 4410/5410 without pin defined 
AT&T 4410/5410 in 132-column mode 
AT&T 4410/5410 terminal in 80-column mode - version 1 
AT&T 4410/5410 terminal in 132-column mode - version 1 
AT&T 4415/5420 in 80-column mode 
AT&T 4415/5420 without changing labels 
AT&T 4415/5420 80 columns in reverse video 
AT&T 4415/5420 reverse video without changing labels 
AT&T 4415/5420 in 132-column mode 
AT&T 4415/5420 in 132-column mode without changing 
labels 

AT&T 4415/5420 132 columns in reverse video 
AT&T 4415/5420 132 columns reverse video 

without changing labels 
AT&T 5418 in 80-column mode 
AT&T 5418 in 132-column mode 
AT&T TELETYPE Model 4420 
AT&T TELETYPE Model 4424 

AT&T TELETYPE Model 4424 in display function group ii 
AT&T 4425/5425 

AT&T 4425/5425 without function keys 
AT&T 4425/5425 without changing labels in 80-column 
mode 

AT&T 4425/5425 in 132-column mode 
AT&T 4425/5425 without function keys in 132-column 
mode 

AT&T 4425/5425 without changing labels in 132-column 
mode 

AT&T TELETYPE Model 4426S 
DASI 450 (same as Diablo 1620) 
DASI 450 in 12-pitch mode 
AT&T-IS 500 terminal 
AT&T 510/510a in 80-column mode 
AT&T 513 bet terminal 
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5320 AT&T 5320 hardcopy terminal 

5420_2 AT&T 5420 model 2 in 80-column mode 

5420^-w AT&T 5420 model 2 in 132-column mode 

5620,dmd AT&T 5620 terminal 88 columns 

5620-24,dmd-24 AT&T TELETYPE Model DMD 5620 in a 24x80 layer 

5620-34,dmd-34 AT&T TELETYPE Model DMD 5620 in a 34x80 layer 

610,610bct AT&T 610 bet terminal in 80-column mode 

610-w,610bct-w AT&T 610 bet terminal in 132-column mode 

7300,pc7300,unix_pc AT&T UNIX PC Model 7300 

735,ti Texas Instruments TI735 and TI725 

745 Texas Instruments TI745 

dumb generic name for terminals that lack reverse 

line-feed and other special escape sequences 

hp Hewlett-Packard (same as 2645) 

Ip generic name for a line printer 

pt505 AT&T Personal Terminal 505 (22 lines) 

pt505-24 AT&T Personal Terminal 505 (24-line mode) 

sync generic name for synchronous TELETYPE Model 

4540-compatible terminals 



Commands whose behavior depends on the type of terminal should accept 
arguments of the form -Tterm where term is one of the names given above; 
if no such argument is present, such commands should obtain the terminal 
type from the environment variable TERM, which, in turn, should contain 
term. 

FILES 

/usr/lib/terminfo/?/* compiled terminal description data base 
SEE ALSO 

curses(3X), profile(4), terminfo(4), environ(5). 

infocmp(lM), sh(l), stty(l), tabs(l), tput(l), tplot(lG), vi(l) in the 
User's/System Administrator's Reference Manual 

Chapter 10 of the Programmer's Guide, 

NOTES 

Not all programs follow the above naming conventions. 
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NAME 

types - primitive system data types 

SYNOPSIS 

#include <sys/types.h> 

DESCRIPTION 

The data types defined in the include file are used in UNIX system code; 
some data of these types are accessible to user code: 

typedef struct { int r[l]; } *physadr; 



typedef long daddr_t; 

typedef char * caddr_.t; 

typedef unsigned char unchar; 

typedef unsigned short ushort; 

typedef unsigned int uint; 

typedef unsigned long ulong; 

typedef ushort ino_.t; 

typedef short cnt_t; 

typedef long time— t; 

typedef int labeL_t[6]; 

typedef short dev_^t; 

typedef long off_t; 

typedef unsigned long paddr_t; 

typedef int key_-t; 

typedef unsigned char use_t; 

typedef short sysid_t; 

typedef short index_t; 

typedef short lock_t; 

typedef unsigned int size_t; 

typedef unsigned short seL_t; 



The form daddr^t is used for disk addresses except in an inode on disk [see 
/s(4)]. Times are encoded in seconds since 00:00:00 GMT, January 1, 1970. 
The major and minor parts of a device code specify kind and unit number 
of a device and are installation-dependent. Offsets are measured in bytes 
from the beginning of a file. The label— t variables are used to save the pro- 
cessor state while another process is running. 

SEE ALSO 

fs(4). 
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NAME 

values - machine-dependent values 

SYNOPSIS 

#include <values.h> 

DESCRIPTION 

This file contains a set of manifest constants, conditionally defined for par- 
ticular processor architectures. 

The model assumed for integers is binary representation (one's or two's 
complement), where the sign is represented by the value of the high-order 
bit. 

BnS(type) The number of bits in a specified type (e.g., int). 

HIBITS The value of a short integer with only the high-order 

bit set (in most implementations, 0x8000). 

HIBITL The value of a long integer with only the high-order 

bit set (in most implementations, 0x80000000). 

HIBITI The value of a regular integer with only the high- 

order bit set (usually the same as HIBITS or HIBITL). 

MAXSHORT The maximum value of a signed short integer (in most 

implementations, 0x7FFF = 32767). 

MAXLONG The maximum value of a signed long integer (in most 

implementations, 0x7FFFFFFF ^ 2147483647). 

MAXINT The maximum value of a signed regular integer (usu- 

ally the same as MAXSHORT or MAXLONG). 

MAXFLOAT, LN_MAXFLOAT The maximum value of a single-precision 

floating-point number, and its natural loga- 
rithm. 

The maximum value of a double-precision 
floating-point number, and its natural loga- 
rithm. 

The minimum positive value of a single- 
precision floating-point number, and its 
natural logarithm. 

MINDOUBLE, LN_MINDOUBLE The minimum positive value of a double- 
precision floating-point number, and its 
natural logarithm. 

The number of significant bits in the mantissa of a 
single-precision floating-point number. 

The number of significant bits in the mantissa of a 
double-precision floating-point number. 



MAXDOUBLE, LN_MAXDOUBLE 



MINFLOAT, LN_MINFLOAT 



FSIGNIF 



DSIGNIF 



SEE ALSO 

intro(3), limits(4), math(5). 
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NAME 

varargs - handle variable argument list 

SYNOPSIS 

#include <varargs.h> 

va—alist 

va— del 

void va^tart(pvar) 
vaJiist pvar; 

type va__arg(pvar, type) 
vaJist pvar; 

void va— end(pvar) 
va— list pvar; 

DESCRIPTION 

This set of macros allows portable procedures that accept variable argument 
lists to be written. Routines that have variable argument lists [such as 
printf(3S)] but do not use varargs are inherently nonportable, as different 
machines use different argument-passing conventions. 

va—alist is used as the parameter list in a function header. 

va— del is a declaration for va-/ilist. No semicolon should follow va—dcL 

va— list is a type defined for the variable used to traverse the list. 

va— start is called to initialize pvar to the beginning of the list. 

va— arg will return the next argument in the list pointed to by pvar. Type is 
the type the argument is expected to be. Different types can be mixed, but 
it is up to the routine to know what type of argument is expected, as it can- 
not be determined at runtime. 

va— end is used to clean up. 

Multiple traversals, each bracketed by va^tart ... va—end, are possible. 
EXAMPLE 

This example is a possible implementation of excel (2), 

#include <varargs.h> 
#define MAXARGS 100 

/* execl is called by 

execl(file, argl, arg2, (char *)0); 

V 

execl(va_alist) 
va_dcl 

{ 

va-Jist ap; 
char *file; 

char *args[MAXARGS]; 
int argno = 0; 
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va_start(ap); 

file = va_arg(ap, char *); 

while ((args[argno++] = va_arg(ap, char *)) != (char *)0) 

va— end(ap); 

return execv(file, args); 

} 

SEE ALSO 

exec(2), printf(3S), vprintf(3S). 

NOTES 

It is up to the calling routine to specify how many arguments there are, 
since it is not always possible to determine this from the stack frame. For 
example, execl is passed a zero pointer to signal the end of the list. Printf 
can tell how many arguments are there by the format. 
It is non-portable to specify a second argument of char, short, or float to 
va—arg, since arguments seen by the called function are not char, short, or 
float, C converts char and short arguments to int and converts float argu- 
ments to double before passing them to a function. 
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NAME 

xtproto - multiplexed channels protocol used by xt(7) driver 
DESCRIPTION 

The xt(7) driver contains routines which implement a multiplexed, multi- 
buffered, full-duplex protocol with guaranteed delivery of ordered data via 
an 8-bit byte data stream. This protocol is used for communication between 
multiple UNIX system host processes and an AT&T windowing terminal 
operating under layers{l). 

The protocol uses packets with a 2-byte header containing a 3-bit sequence 
number, 3-bit channel number, control flag, and data size. The data part of 
a packet may not be larger than 32 bytes. The trailer contains a CRC-16 
code in 2 bytes. Each channel is double-buffered. 

Correctly received packets in sequence are acknowledged with a control 
packet containing an ACK; however, out of sequence packets generate a con- 
trol packet containing a NAK, which will cause the retransmission in 
sequence of all unacknowledged packets. 

Unacknowledged packets are retransmitted after a timeout interval which is 
dependent on baud rate. Another timeout parameter specifies the interval 
after which incomplete receive packets are discarded. 

FILES 

/usr/include/sys/xtproto.h channel multiplexing protocol definitions 
SEE ALSO 

layers(5). 

layers(l), xt(7) in the User's/System Administrator's Reference Manual 



- 1 - 



PERMUTED INDEX 



13tol, ltol3: convert between 3-byte integers and long/ 13tol(3C) 

i286emul: emulate 80286 i286emul(l) 

x286emul: emulate XENIX 80286 x286emul(l) 

long integer and base-64/ a641, 164a: convert between a641(3C) 

abort: generate an abort fault abort(3C) 

fault, abort: generate an abort abort(3C) 

value, abs: return integer absolute abs(3C) 

abs: return integer absolute value abs(3C) 

/floor, ceiling, remainder, absolute value functions floor(3M) 

t accept! accept a connect request t_accept(3N) 

utime: set file access and modification times utime(2) 

accessibility of a file, access: determine access(2) 

sputl, sgetl: access long integer data in a/ sputl(3X) 

Idfcn: common object file access routines ldfcn(4) 

/setutent, endutent, utmpname: access utmp file entry getut(3C) 

access: determine accessibility of a file access(2) 

enable or disable process accounting, acct: acct(2) 

acct: per-process accounting file format acct(4) 

process accounting, acct: enable or disable acct(2) 

file format, acct: per-process accounting . acct(4) 

orderly release/ t_rcvrel: acknowledge receipt of an t_rcvrel(3N) 

trig: sin, cos, tan, asin, acos, atan, atan2:/ trig(3M) 

current SCCS file editing activity, sact: print sact(l) 

putenv: change or add value to environment putenv(3C) 

endpoint. t_bind: bind an address to a transport t_bind(3N) 

SCCS files, admin: create and administer admin(l) 

admin: create and administer SCCS files admin(l) 

uadmin: administrative control uadmin(2) 

alarm: set a process alarm clock alarm(2) 

clock, alarm: set a process alarm alarm(2) 

t_ alloc; allocate a library structure t_alloc(3N) 

change data segment space allocation, brk, sbrk: brk(2) 

realloc, calloc: main memory allocator, malloc, free, malloc(3C) 

mallinfo: fast main memory allocator, /calloc, mallopt malloc(3X) 

link editor output, a.out: common assembler and a.out(4) 

maintainer for portable/ ar: archive and library ar(l) 

format, ar: common archive file ar(4) 

for portable archives, ar: archive and library maintainer ar(l) 

cpio: format of cpio archive cpio(4) 

ar: common archive file format ar(4) 

header of a member of an archive file, /the archive ldahread(3X) 

formats, convert: convert archive files to common convert(l) 

an archive/ Idahread: read the archive header of a member of ldahread(3X) 

maintainer for portable archives, /archive and library ar(l) 

varargs: handle variable argument list varargs(5) 

formatted output of a varargs argument list, /print vprintf(3S) 

getopt: get option letter from argument vector getopt(3C) 

as: common assembler as(l) 

and/ /gmtime, asctime, cftime, ascftime, tzset: convert date ctime(3C) 

ascii:mapof ASCII character set ascii(5) 

set. ascii: map of ASCII character ascii(5) 



- 1 - 



Permuted Index 



long integer and base-64 ASCII string, /convert between a641(3C) 

ctime, localtime, gmtime, asctime, cftime, ascftime,/ ctime(3C) 

trig: sin, cos, tan, asin, acos, atan, atan2:/ trig(3M) 

output, a.out: common assembler and link editor a.out(4) 

as: common assembler as(l) 

assertion, assert: verify program assert(3X) 

assert: verify program assertion assert(3X) 

setbuf, setvbuf: assign buffering to a stream setbuf(3S) 

/sin, cos, tan, asin, acos, atan, atan2: trigonometric/ trig(3M) 

cos, tan, asin, acos, atan, atan2: trigonometric/ /sin, trig(3M) 

double-precision/ strtod, atof: convert string to strtod(3C) 

integer, strtol, atol, atoi: convert string to strtol(3C) 

integer, strtol, atol, atoi: convert string to strtol(3C) 

log of failed login attempts, /usr/adm/loginlog: loginlog(4) 

ungetc: push character back into input stream ungetc(3S) 

terminal capability data base, terminfo: terminfo(4) 

between long integer and base-64 ASCII string, /convert a641(3C) 

cb: C program beautifier cb(l) 

jO, jl, jn, yO, yl, yn: Bessel functions, bessel: bessel(3M) 

yn: Bessel functions, bessel: jO, jl, jn, yO, yl, bessel(3M) 

fread, f write: binary input/output fread(3S) 

bsearch: binary search a sorted table bsearch(3C) 

tfmd, tdelete, twalk: manage binary search frees, tsearch, tsearch(3C) 

endpoint. t_bind: bind an address to a transport t_bind(3N) 

sync: update super block sync(2) 

space allocation, brk, sbrk: change data segment brk(2) 

sorted table, bsearch: binary search a bsearch(3C) 

stdio: standard buffered input/output package stdio(3S) 

setbuf, setvbuf: assign buffering to a stream setbuf(3S) 

size: print section sizes in bytes of common object files size(l) 

swab: swap bytes swab(3C) 

cc: C compiler. cc(l) 

cflow: generate C flowgraph cflow(l) 

cpp: the C language preprocessor q?p(l) 

cb: C program beautifier cb(l) 

lint: a C program checker lint(l) 

cxref: generate C program cross-reference cxref(l) 

interactively examine a C program, cscope: cscope(l) 

ctrace: C program debugger ctrace(l) 

object file, list: produce C source listing from a common list(l) 

data returned by stat system call, stat: stat(5) 

malloc, free, realloc, calloc: main memory allocator malloc(3C) 

fast/ malloc, free, realloc, calloc, mallopt, mallinfo: malloc(3X) 

intro: introduction to system calls and error numbers intro(2) 

terminfo: terminal capability data base terminfo(4) 

pnch: file format for card images pnch(4) 

cb: C program beautifier cb(l) 

cc: C compiler cc(l) 

create a front-end to the cc command, gencc: gencc(l) 

ccoff: convert a COFF file ccoff(l) 

commentary of an SCCS delta, cdc: change the delta cdc(l) 

ceiling, remainder,/ floor, ceil, fmod, fabs: floor, floor(3M) 

/ceil, fmod, fabs: floor, ceiling, remainder, absolute/ floor(3M) 
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cflow: generate C flowgraph cflow(l) 

/localtime, gmtime, asctime, cftime, ascftime, tzset:/ ctime(3C) 

strings, cftime: language specific cftime(4) 

delta: make a delta (change) to an SCCS file delta(l) 

pipe: create an interprocess channel pipe(2) 

xt(7)/ xtproto: multiplexed channels protocol used by xtproto(5) 

stream, ungetc: push character back into input ungetc(3S) 

—toupper, setchrclass: character hand /_tolower, ctype(3C) 

user, cuserid: get character login name of the cuserid(3S) 

/getchar, fgetc, getw: get character or word from a/ getc(3S) 

/putchar, fputc, putw: put character or word on a stream putc(3S) 

ascii: map of ASCII character set ascii(5) 

directory, chdir: change working chdir(2) 

lint: a C program checker lint(l) 

systems processed by fsck and/ checklist: list of file checklist(4) 

times: get process and child process times times(2) 

terminate, wait: wait for child process to stop or wait(2) 

libraries tool, chkshlib: compare shared chkshlib(l) 

chmod: change mode of file chmod(2) 

of a file, chown: change owner and group chown(2) 

chroot: change root directory chroot(2) 

status/ ferror, feof, dearerr, fileno: stream ferror(3S) 

listener, nlsgetcall: get client's data passed via the nlsgetcall(3N) 

alarm: set a process alarm clock alarm(2) 

/the frequency of the system clock in ticks per second gethz(3C) 

clock: report CPU time used clock(3C) 

Idclose, Idaclose: close a common object file ldclose(3X) 

close: close a file descriptor close(2) 

t_close: close a transport endpoint L_close(3N) 

descriptor, close: close a file close(2) 

fclose, fflush: close or flush a stream fclose(3S) 

telldir, seekdir, rewinddir, closedir: directory/ /readdir, directory(3C) 

dis: object code disassembler dis(l) 

ccoff: convert a COFF file ccoff(l) 

comb: combine SCCS deltas comb(l) 

comb: combine SCCS deltas comb(l) 

create a front-end to the cc command, gencc: gencc(l) 

system: issue a shell command system(3S) 

introduction to programming commands, intro: intro(l) 

manipulate the object file comment section, mcs: mcs(l) 

cdc: change the delta commentary of an SCCS delta cdc(l) 

ar: common archive file format ar(4) 

editor output, a.out: common assembler and link . a.out(4) 

as: common assembler as(l) 

convert archive files to common formats, convert: convert(l) 

routines. Idfcn: common object file access ldfcn(4) 

conv: common object file converter conv(l) 

cprs: compress a common object file cprs(l) 

Idopen, Idaopen: open a common object file for/ ldopen(3X) 

/line number entries of a common object file function ldlread(3X) 

Idclose, Idaclose: close a common object file ldclose(3X) 

read the file header of a common object file, Idfhread: ldfhread(3X) 

entries of a section of a common object file, /number ldlseek(3X) 
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the oprional file header of a common object file, /seek to ldohseek(3X) 

/entries of a section of a common object file ldrseek(3X) 

/section header of a common object file ldshread(3X) 

an indexed/named section of a common object file, /seek to ldsseek(3X) 

of a symbol table entry of a common object file, /the index ldtbindex(3X) 

symbol table entry of a common object file, /indexed ldtbread(3X) 

seek to the symbol table of a common object file. Idtbseek: ldtbseek(3X) 

line number entries in a common object file, linenum: hnenum(4) 

C source listing from a common object file, /produce list(l) 

nm: print name list of common object file nm(l) 

relocation information for a common object file, reloc: reloc(4) 

scnhdr: section header for a common object file scnhdr(4) 

line number information from a common object file, /and strip(l) 

/retrieve symbol name for common object file symbol/ ldgetname(3X) 

table format, syms: common object file symbol syms(4) 

filehdr: file header for common object files filehdr(4) 

Id: link editor for common object files ld(l) 

section sizes in bytes of common object files, /print size(l) 

/ftok: standard interprocess communication package stdipc(3C) 

descriptions, infocmp: compare or print out terminfo infocmp(lM) 

chkshlib: compare shared libraries tool chkshlib(l) 

sees file, sccsdiff: compare two versions of an sccsdiff(l) 

expression, regcmp, regex: compile and execute regular regcmp(3X) 

regexp: regular expression compile and match routines regexp(5) 

regcmp: regular expression compile regcmp(l) 

term: format of compiled term file term(4) 

cc: C compiler cc(l) 

tic: terminfo compiler tic(lM) 

yacc: yet another compiler-compiler yacc(l) 

erf, erfc: error function and complementary error function erf(3M) 

cprs: compress a common object file cprs(l) 

table entry of a/ Idtbindex: compute the index of a symbol ldtbindex(3X) 

t__rcvconnect: receive the confirmation from a connect/ t_rcvconnect(3) 

t_accept: accept a connect request t_accept(3N) 

t_listen: listen for a connect request t_listen(3N) 

the confirmation from a connect request, /receive t_rcvconnect(3) 

an outgoing terminal line connection, dial: establish dial(3C) 

or expedited data sent over a connection, /receive data t_rcv(3N) 

data or expedited data over a connection. t_snd: send t_snd(3N) 

t_connect: establish a connection with another/ t_connect(3N) 

for implementation-specific constants, /file header limits(4) 

math: math functions and constants math(5) 

file header for symbolic constants, unistd: unistd(4) 

ioctl: control device ioctl(2) 

fcntl: file control fcntl(2) 

floating point environment control, /fpsetsticky: IEEE fpgetround(3C) 

jagent: host control of windowing terminal jagent(5) 

msgctl: message control operations msgctl(2) 

semctl: semaphore control operations semctl(2) 

shmctl: shared memory control operations shmctl(2) 

fcntl: file control options fcntl(5) 

uadmin: administrative control uadmin(2) 

vc: version control vc(l) 
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converter, conv: common object file conv(l) 

terminals, term: conventional names for term(5) 

ccoff: convert a COFF file ccoff(l) 

common formats, convert: convert archive files to convert(l) 

integers and/ 13tol, ltol3: convert between 3-byte 13tol(3C) 

and base-64 ASCII/ a641, 164a: convert between long integer a641(3C) 

to common formats, convert: convert archive files convert(l) 

/cftime, ascftime, tzset: convert date and time to/ ctime(3C) 

to string, ecvt, fcvt, gcvt: convert floating-point number ecvt(3C) 

scanf, fscanf, sscanf: convert formatted input scanf(3S) 

strtod, atof: convert string to/ strtod(3C) 

strtol, atol, atoi: convert string to integer strtol(3C) 

conv: common object file converter conv(l) 

file, core: format of core image core(4) 

core: format of core image file core(4) 

atan2:/ trig: sin, cos, tan, asin, acos, atan, trig(3M) 

functions, sinh, cosh, tanh: hyperbolic sinh(3M) 

display line-by-line execution count profile data. Iprof: Iprof(l) 

cpio: format of cpio archive cpio(4) 

cpio: format of cpio archive cpio(4) 

preprocessor, cpp: the C language cpp(l) 

file, cprs: compress a common object cprs(l) 

clock: report CPU time used clock(3C) 

rewrite an existing one. creat: create a new file or creat(2) 

command, gencc: create a front-end to the cc gencc(l) 

file, tmpnam, tempnam: create a name for a temporary tmpnam(3S) 

an existing one. creat: create a new file or rewrite creat(2) 

fork: create a new process fork(2) 

mkshlib: create a shared library mkshlib(l) 

ctags: create a tags file ctags(l) 

tmpfile: create a temporary file tmpfile(3S) 

channel, pipe: create an interprocess pipe(2) 

files, admin: create and administer SCCS admin(l) 

umask: set and get file creation mask umask(2) 

cxref: generate C program cross-reference cxref(l) 

item: CRT item routines item(3X) 

menu: CRT menu routines menu(3X) 

encryption functions, crypt: password and file crypt(3X) 

generate hashing encryption, crypt, setkey, encrypt: crypt(3C) 

a C program, cscope: interactively examine cscope(l) 

ctags: create a tags file ctags(l) 

for terminal, ctermid: generate file name ctermid(3S) 

asctime, cftime, ascftime,/ ctime, localtime, gmtime, ctime(3C) 

ctrace: C program debugger ctrace(l) 

islower, isupper, isalpha,/ ctype: isdigit, isxdigit, ctype(3C) 

endpoint. t_look: look at the current event on a transport t_look(3N) 

activity, sact: print current SCCS file editing sact(l) 

t_getstate: get the current state t_getstate(3N) 

uname: get name of current UNIX system uname(2) 

slot in the utmp file of the current user, /find the ttyslot(3C) 

getcwd: get path name of current working directory getcwd(3C) 

scr_dump: format of curses screen image file scr_dump(4) 

handling and optimization/ curses: terminal screen curses(3X) 
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name of the user, cuserid: get character login cuserid(3S) 

cross-reference, cxref: generate C program cxref(l) 

terminfo: terminal capability data base terminfo(4) 

t_rcvuderr: receive a unit data error indication t_rcvuderr(3N) 

/sgetl: access long integer data in a machine-independent/ sputl(3X) 

plock: lock process, text, or data in memory plock(2) 

execution count profile data, /display line-by-line lprof(l) 

connection. t_snd: send data or expedited data over a t_snd(3N) 

over a/ t_rcv: receive data or expedited data sent t_rcv(3N) 

t_snd: send data or expedited data over a connection t_snd(3N) 

nlsgetcall: get client's data passed via the listener nlsgetcall(3N) 

prof: display profile data prof(l) 

call. Stat: data returned by stat system stat(5) 

brk, sbrk: change data segment space allocation brk(2) 

/receive data or expedited data sent over a connection t_rcv(3N) 

types: primitive system data types types(5) 

t_rcvudata: receive a data unit t_rcvudata(3N) 

t_sndudata: send a data unit t_sndudata(3N) 

/ascftime, tzset: convert date and time to string ctime(3C) 

ctrace: C program debugger ctrace(l) 

sdb: symbolic debugger sdb(l) 

timezone: set default system time zone timezone(4) 

delta commentary of an SCCS delta, cdc: change the cdc(l) 

file, delta: make a delta (change) to an SCCS delta(l) 

delta, cdc: change the delta commentary of an SCCS cdc(l) 

rmdel: remove a delta from an SCCS file rmdel(l) 

to an SCCS file, delta: make a delta (change) delta(l) 

comb: combine SCCS deltas comb(l) 

compare or print out terminfo descriptions, infocmp: infocmp(lM) 

close: close a file descriptor close(2) 

dup: duplicate an open file descriptor dup(2) 

dup2: duplicate an open file descriptor dup2(3C) 

file, access: determine accessibility of a access(2) 

ioctl: control device ioctl(2) 

terminal line connection, dial: establish an outgoing dial(3C) 

dir: format of directories dir(4) 

dir: format of directories dir(4) 

chdir: change working directory chdir(2) 

chroot: change root directory chroot(2) 

getdents: read directory entries and put in a/ getdents(2) 

file-system-independent directory entry, dirent: dirent(4) 

unlink: remove directory entry unlink(2) 

path name of current working directory, getcwd: get getcwd(3C) 

mkdir: make a directory mkdir(2) 

telldir, seekdir, rewinddir,/ directory: opendir, readdir, directory(3C) 

/seekdir, rewinddir, closedir: directory operations directory(3C) 

ordinary file/ mknod: make a directory or a special or mknod(2) 

rmdir: remove a directory rmdir(2) 

file-system-independent/ dirent: dirent(4) 

dis: object code disassembler dis(l) 

t_unbind: disable a transport endpoint L_unbind(3N) 

acct: enable or disable process accounting acct(2) 

dis: object code disassembler dis(l) 
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t_snddis: send user-initiated disconnect request t_snddis(3N) 

retrieve information from disconnect. t_rcvdis: t_rcvdis(3N) 

count profile data. Iprof: display line-by-line execution Iprof(l) 

prof: display profile data pTof{l) 

XENIX object file, hdr: display selected parts of a hdr(l) 

h)^ot: Euclidean distance function hypot(3M) 

/lcong48: generate uniformly distributed pseudo-random/ drand48(3C) 

/atof: convert string to double-precision number strtod(3C) 

nrand48, mrand48, jrand48,/ drand48, erand48, lrand48, drand48(3C) 

protocol used by xt(7) driver, /multiplexed channels xtproto(5) 

an object file, dump: dump selected parts of dump(l) 

object file, dump: dump selected parts of an dump(l) 

descriptor, dup: duplicate an open file dup(2) 

descriptor. dup2: duplicate an open file dup2(3C) 

descriptor, dup: duplicate an open file dup(2) 

descriptor. dup2: duplicate an open file dup2(3C) 

floating-point number to/ ecvt, fcvt, gcvt: convert ecvt(3C) 

program, end, etext, edata: last locations in end(3C) 

sact: print current SCCS file editing activity sact(l) 

files. Id: link editor for common object ld(l) 

common assembler and link editor output, a.out: a.out(4) 

/user, real group, and effective group IDs getuid(2) 

and/ /getegid: get real user, effective user, real group, getuid(2) 

i286emul: emulate 80286. i286emul(l) 

x286emul: emulate XENIX 80286 x286emul(l) 

accounting, acct: enable or disable process acct(2) 

encryption, crypt, setkey, encrypt: generate hashing crypt(3C) 

encrypt: generate hashing encryption, crypt, setkey, crypt(3C) 

crypt: password and file encryption functions crypt(3X) 

locations in program, end, etext, edata: last end(3C) 

/getgrgid, getgmam, setgrent, endgrent, fgetgrent: get group/ getgrent(3C) 

bind an address to a transport endpoint. t_bind: t_bind(3N) 

t_close: close a transport endpoint t_close(3N) 

current event on a transport endpoint. LJook: look at the t_look(3N) 

t_open: establish a transport endpoint t_open(3N) 

manage options for a transport endpoint. t_optmgmt: t_optmgmt(3N) 

t_unbind: disable a transport endpoint t_unbind(3N) 

/getpwuid, getpwnam, setpwent, endpwent, fgetpwent: get/ getpwent(3C) 

utmp/ /pututline, setutent, endutent, utmpname: access getut(3C) 

getdents: read directory entries and put in a/ getdents(2) 

nlist: get entries from name list nlist(3C) 

file, linenum: line number entries in a common object linenum(4) 

file/ /manipulate line number entries of a common object ldlread(3X) 

/Idnlseek: seek to line number entries of a section of a/ ldlseek(3X) 

/Idnrseek: seek to relocation entries of a section of a/ ldrseek(3X) 

/directory entry dirent(4) 

utmp, wtmp: utmp and wtmp entry formats utmp(4) 

fgetgrent: get group file entry, /setgrent, endgrent, getgrent(3C) 

fgetpwent: get password file entry, /setpwent, endpwent, getpwent(3C) 

utmpname: access utmp file entry, /setutent, endutent, getut(3C) 

object file symbol table entry, /symbol name for common ldgetname(3X) 

/the index of a symbol table entry of a common object file ldtbindex(3X) 

/read an indexed symbol table entry of a common object file ldtbread(3X) 
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putpwent: write password file entry putpwent(3C) 

unlink: remove directory entry unlink(2) 

environ: user environment environ(5) 

profile: setting up an environment at login time profile(4) 

/IEEE floating point environment control fpgetround(3C) 

environ: user environment environ(5) 

getenv: return value for environment name getenv(3C) 

putenv: change or add value to environment putenv(3C) 

mrand48, jrand48,/ drand48, erand48, lrand48, nrand48, drand48(3C) 

complementary error function, erf, erfc: error function and erf(3M) 

complementary error/ erf, erfc: error function and erf(3M) 

system error/ perror, ermo, sys_errlist, sys_nerr: perror(3C) 

complementary/ erf, erfc: error function and erf(3M) 

function and complementary error function, /erfc: error erf(3M) 

receive a unit data error indication. t_rcvuderr: t__rcvuderr(3N) 

t_error: produce error message t_error(3N) 

sys_errlist, sys_nerr: system error messages, /ermo, perror(3C) 

to system calls and error numbers, /introduction intro(2) 

matherr: error-handling function matherr(3M) 

another transport/ t_connect: establish a connection with t_connect(3N) 

endpoint. t_open: establish a transport L_open(3N) 

line connection, dial: establish an outgoing terminal dial(3C) 

in program, end, etext, edata: last locations end(3C) 

hypot: Euclidean distance function hypot(3M) 

t_look: look at the current event on a transport endpoint t_look(3N) 

cscope: interactively examine a C program cscope(l) 

execve, exedp, execvp:/ exec: execl, execv, execle, exec(2) 

execlp, execvp: execute/ exec: execl, execv, execle, execve, exec(2) 

execvp:/ exec: execl, execv, execle, execve, execlp, exec(2) 

/execl, execv, execle, execve, execlp, execvp: execute a/ exec(2) 

execve, execlp, execvp: execute a file, /execle, exec(2) 

regcmp, regex: compile and execute regular expression regcmp(3X) 

Iprof: display line-by-line execution count profile data lprof(l) 

sleep: suspend execution for interval sleep(3C) 

monitor: prepare execution profile monitor(3C) 

profil: execution time profile profil(2) 

execvp: execute/ exec: execl, execv, execle, execve, execlp, exec(2) 

exec: execl, execv, execle, execve, execlp, execvp:/ exec(2) 

/execv, execle, execve, execlp, execvp: execute a file exec(2) 

a new file or rewrite an existing one. creat: create creat(2) 

process, exit, _exit: terminate exit(2) 

exit, —exit: terminate process exit(2) 

exponential, logarithm,/ exp, log, loglO, pow, sqrt: exp(3M) 

t_snd: send data or expedited data over a/ t_snd(3N) 

L_rcv: receive data or expedited data sent over a/ t_rcv(3N) 

exp, log, loglO, pow, sqrt: exponential, logarithm, power,/ exp(3M) 

routines, regexp: regular expression compile and match regexp(5) 

regcmp: regular expression compile regcmp(l) 

compile and execute regular expression, regcmp, regex: regcmp(3X) 

remainder,/ floor, ceil, fmod, fabs: floor, ceiling, floor(3M) 

/usr/adm/loginlog: log of failed login attempts loginlog(4) 

data in a machine-independent fashion, /access long integer sputl(3X) 

/calloc, mallopt, mallinfo: fast main memory allocator malloc(3X) 
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abort: generate an abort fault abort(3C) 

a stream, fclose, fflush: dose or flush fclose(3S) 

fcntl: file control fcntl(2) 

fcntl: file control options fcntl(5) 

floating-point number/ ecvt, fcvt, gcvt: convert ecvt(3C) 

fopen, freopen, fdopen: open a stream fopen(3S) 

status inquiries, ferror, feof, clearerr, fileno: stream ferror(3S) 

fileno: stream status/ f error, feof, clearerr, ferror(3S) 

stream, fclose, fflush: close or flush a fclose(3S) 

word from a/ getc, getchar, fgetc, getw: get character or getc(3S) 

/getgmam, setgrent, endgrent, fgetgrent: get group file/ getgrent(3C) 

/getpwnam, setpwent, endpwent, fgetpwent: get password file/ getpwent(3C) 

stream, gets, fgets: get a string from a gets(3S) 

routines, fieldtype: FIELDTYPE library fieldtype(3X) 

fieldtype: FIELDTYPE library routines fieldtype(3X) 

special or ordinary file or a FIFO, /make a directory or a mknod(2) 

times, utime: set file access and modification utime(2) 

Idfcn: common object file access routines ldfcn(4) 

determine accessibility of a file, access: access(2) 

ccoff: convert a COFF file ccoff(l) 

chmod: change mode of file chmod(2) 

change owner and group of a file, chown: chown(2) 

mcs: manipulate the object file comment section mcs(l) 

fcnri: file control fcntl(2) 

fcntl: file control options fcnU(5) 

conv: common object file converter conv(l) 

core: format of core image file core(4) 

cprs: compress a common object file cprs(l) 

umask: set and get file creation mask umask(2) 

ctags: create a tags file ctags(l) 

a delta (change) to an SCCS file, delta: make delta(l) 

close: close a file descriptor close(2) 

dup: duplicate an open file descriptor dup(2) 

dup2: duplicate an open file descriptor dup2(3C) 

selected parts of an object file, dump: dump dump(l) 

sact: print current SCCS file editing activity sact(l) 

crypt: password and file encryption functions crypt(3X) 

endgrent, fgetgrent: get group file entry, /setgrent, getgrent(3C) 

fgetpwent: get password file entry, /endpwent, getpwent(3C) 

utmpname: access utmp file entry, /endutent, getut(3C) 

putpwent: write password file entry putpwent(3C) 

execlp, execvp: execute a file, /execv, execle, execve, exec(2) 

Idaopen: open a common object file for reading. Idopen, ldopen(3X) 

acct: per-process accounting file format acct(4) 

ar: common archive file format ar(4) 

pnch: file format for card images pnch(4) 

mdevice: file format mdevice(4) 

mfsys: file format mfsys(4) 

mtune: file format mtune(4) 

sdevice: file format sdevice(4) 

sfsys: file format sfsys(4) 

stune: file format stune(4) 

intro: introduction to file formats intro(4) 
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entries of a common object file function, /line number ldlread(3X) 

get: get a version of an SCCS file get(l) 

group: group file group(4) 

parts of a XENIX object file, hdr: display selected hdr(l) 

files, filehdr: file header for common object filehdr(4) 

limits: file header for/ limits(4) 

constants, unistd: file header for symbolic unistd(4) 

file. Idfhread: read the file header of a common object ldfhread(3X) 

Idohseek: seek to the optional file header of a common object/ ldohseek(3X) 

issue: issue identification file issue(4) 

of a member of an archive file, /read the archive header ldahread(3X) 

close a common object file. Idclose, Idaclose: ldclose(3X) 

file header of a common object file. Idfhread: read the ldfhread(3X) 

a section of a common object file, /line number entries of ldlseek(3X) 

file header of a common object file, /seek to the optional ldohseek(3X) 

a section of a common object file, /relocation entries of ldrseek(3X) 

header of a common object file, /indexed/named section ldshread(3X) 

section of a common object file, /to an indexed/named ldsseek(3X) 

table entry of a common object file, /the index of a symbol ldtbindex(3X) 

table entry of a common object file, /read an indexed symbol ldtbread(3X) 

table of a common object file, /seek to the symbol ldtbseek(3X) 

entries in a common object file, linenum: line number linenum(4) 

link: link to a file link(2) 

listing from a common object file, list: produce C source list(l) 

ctermid: generate file name for terminal ctermid(3S) 

mktemp: make a unique file name mktemp(3C) 

name list of common object file, nm: print nm(l) 

/find the slot in the utmp file of the current user ttyslot(3C) 

or a special or ordinary file or a FIFO, /a directory mknod(2) 

one. creat: create a new file or rewrite an existing creat(2) 

passwd: password file passwd(4) 

/rewind, ftell: reposition a file pointer in a stream fseek(3S) 

Iseek: move read/write file pointer lseek(2) 

prs: print an SCCS file prs(l) 

read: read from file read(2) 

for a common object file, /relocation information reloc(4) 

Sharing name server master file, rfmaster: Remote File rfmaster(4) 

remove a delta from an SCCS file, rmdel: rmdel(l) 

two versions of an SCCS file, sccsdiff: compare sccsdiff(l) 

sccsfile: format of SCCS file sccsfile(4) 

header for a common object file, scnhdr: section scnhdr(4) 

format of curses screen image file. scr_dump: scr_dump(4) 

master file, rfmaster: Remote File Sharing name server rfmaster(4) 

Stat, fstat: get file status stat(2) 

printable strings in an object file, strings: find the strings(l) 

from a common object file, /line number information strip(l) 

/symbol name for common object file s)anbol table entry ldgetname(3X) 

s)ans: common object file symbol table format syms(4) 

volume, fs: file system: format of system fs(4) 

statfs, fstatfs: get file system information statfs(2) 

mount: mount a file system mount(2) 

ustat: get file system statistics ustat(2) 

mnttab: mounted file system table mnttab(4) 
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sysfs: get file system type information sysfs(2) 

umount: unmount a file system umount(2) 

and/ checklist: list of file systems processed by fsck checklist(4) 

term: format of compiled term file term(4) 

tmpfile: create a temporary file tmpfile(3S) 

create a name for a temporary file, tmpnam, tempnam: tmpnam(3S) 

ftw: walk a file tree ftw(3C) 

undo a previous get of an SCCS file, unget: unget(l) 

val: validate sees file val(l) 

write: write on a file write(2) 

common object files, filehdr: file header for filehdr(4) 

f error, feof, clearerr, fileno: stream status/ ferror(3S) 

create and administer SCeS files, admin: admin(l) 

file header for common object files, filehdr: filehdr(4) 

format specification in text files, fspec: fspec(4) 

string, format of graphical files, /graphical primitive gps(4) 

link editor for common object files. Id: ld(l) 

lockf: record locking on files lockf(3e) 

in bytes of common object files, /print section sizes size(l) 

convert: convert archive files to common formats convert(l) 

what: identify SeCS files what(l) 

directory entry, dirent: file-system-independent dirent(4) 

directory entries and put in a file-system-independent/ /read getdents(2) 

fstab: file-system-table fstab(4) 

ttyname, isatty: find name of a terminal ttyname(3C) 

object library, lorder: find ordering relation for an lorder(l) 

an object file, strings: find the printable strings in strings(l) 

of the current user, ttyslot: find the slot in the utmp file ttyslot(3C) 

/fpgetsticky, fpsetsticky: IEEE floating point environment/ fpgetround(3e) 

isnand, isnanf: test for floating point NaN/ isnan: isnan(3e) 

ecvt, fcvt, gcvt: convert floating-point number to/ ecvt(3e) 

/modf: manipulate parts of floating-point numbers frexp(3e) 

floor, ceiling, remainder,/ floor, ceil, fmod, fabs: floor(3M) 

floor, ceil, fmod, fabs: floor, ceiling, remainder,/ floor(3M) 

cflow: generate e flowgraph cflow(l) 

fclose, fflush: close or flush a stream fclose(3S) 

remainder,/ floor, ceil, fmod, fabs: floor, ceiling, floor(3M) 

stream, fopen, freopen, fdopen: open a fopen(3S) 

fork: create a new process fork(2) 

form: FORM library routines form(3X) 

form: FORM library routines form(3X) 

per-process accounting file format, acct: acct(4) 

service request/ nlsrequest: format and send listener nlsrequest(3N) 

ar: common archive file format ar(4) 

pnch: file format for card images pnch(4) 

in a file-system-independent format, /entries and put getdents(2) 

mdevice: file format mdevice(4) 

mfsys: file format mfsys(4) 

mtune: file format mtune(4) 

inode: format of an inode inode(4) 

term: format of compiled term file term(4) 

core: format of core image file core(4) 

cpio: format of cpio archive cpio(4) 
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file. scr_dump: format of curses screen image scr_dump(4) 

dir: format of directories dir(4) 

/graphical primitive string, format of graphical files gps(4) 

sccsfile: format of SCCS file sccsfile(4) 

fs: file system: format of system volume fs(4) 

sdevice: file format sdevice(4) 

sfsys: file format sfsys(4) 

files, fspec: format specification in text fspec(4) 

stune: file format stune(4) 

object file symbol table format, syms: common syms(4) 

archive files to common formats, convert: convert convert(l) 

intro: introduction to file formats intro(4) 

wtmp: utmp and wtmp entry formats, utmp, utmp(4) 

scanf, fscanf, sscanf: convert formatted input scanf(3S) 

/vfprintf, vsprintf: print formatted output of a varargs/ vprintf(3S) 

fprintf, sprintf: print formatted output, printf, printf(3S) 

fpgetround, fpsetround, fpgetmask, fpsetmask,/ fpgetround(3C) 

fpgetmask, fpsetmask,/ fpgetround, fpsetround, fpgetround(3C) 

/fpgetmask, fpsetmask, fpgetsticky, fpsetsticky: IEEE/ fpgetround(3C) 

formatted output, printf, fprintf, sprintf: print printf(3S) 

/fpsetround, fpgetmask, fpsetmask, fpgetsticky,/ fpgetround(3C) 

fpsetmask,/ fpgetround, fpsetround, fpgetmask, fpgetround(3C) 

point/ /fpsetmask, fpgetsticky, fpsetsticky: IEEE floating fpgetround(3C) 

word on a/ putc, putchar, fputc, putw: put character or putc(3S) 

stream, puts, fputs: put a string on a puts(3S) 

input/output, fread, fwrite: binary fread(3S) 

t_free: free a library structure t_free(3N) 

memory allocator, malloc, free, realloc, calloc: main malloc(3C) 

mallopt, mallinfo:/ malloc, free, realloc, calloc, malloc(3X) 

stream, fopen, freopen, fdopen: open a fopen(3S) 

in ticks/ gethz: return the frequency of the system clock gethz(3C) 

parts of floating-point/ frexp, Idexp, modf: manipulate frexp(3C) 

list: produce C source listing from a common object file list(l) 

/and line number information from a common object file strip(l) 

/receive the confirmation from a connect request t_rcvconnect(3) 

getw: get character or word from a stream, /fgetc, getc(3S) 

gets, fgets: get a string from a stream gets(3S) 

rmdel: remove a delta from an SCCS file rmdel(l) 

getopt: get option letter from argument vector getopt(3C) 

t_rcvdis: retrieve information from disconnect t_rcvdis(3N) 

read: read from file read(2) 

nlist: get entries from name list nlist(3C) 

getpw: get name from UID getpw(3C) 

gencc: create a front-end to the cc command gencc(l) 

system volume, fs: file system: format of fs(4) 

formatted input, scanf, fscanf, sscanf: convert scanf(3S) 

of file systems processed by fsck and ncheck. /list checklist(4) 

reposition a file pointer in/ fseek, rewind, ftell: fseek(3S) 

text files, fspec: format specification in fspec(4) 

fstab: file-system-table fstab(4) 

Stat, fstat: get file status stat(2) 

information, statfs, fstatfs: get file system statfs(2) 

pointer in a/ fseek, rewind, ftell: reposition a file fseek(3S) 
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communication/ stdipc: ftok: standard interprocess stdipc(3C) 

ftw: walk a file tree ftw(3C) 

error/ erf, erfc: error function and complementary erf(3M) 

and complementary error function, /error function erf(3M) 

gamma: log gamma function gamma(3M) 

hypot: Euclidean distance function hypot(3M) 

of a common object file function, /line number entries ldlread(3X) 

libwindows: windowing terminal function library libwindows(3X) 

matherr: error-handling function matherr(3M) 

prof: profile within a function prof (5) 

math: math functions and constants math(5) 

intro: introduction to functions and libraries intro(3) 

jO, jl/ jn, yO, yl, yn: Bessel functions, bessel: bessel(3M) 

password and file encryption functions, crypt: crypt(3X) 

logarithm, power, square root functions, /sqrt: exponential, exp(3M) 

remainder, absolute value functions, /floor, ceiling, floor(3M) 

sinh, cosh, tanh: hyperbolic functions sinh(3M) 

sysi86: machine-specific functions sysi86(2) 

atan, atan2: trigonometric functions, /tan, asin, acos, trig(3M) 

fread, fwrite: binary input/output fread(3S) 

gamma: log gamma function gamma(3M) 

gamma: log gamma function gamma(3M) 

number to string, ecvt, fcvt, gcvt: convert floating-point ecvt(3C) 

the cc command, gencc: create a front-end to gencc(l) 

abort: generate an abort fault abort(3C) 

cflow: generate C flowgraph cflow(l) 

cross-reference, cxref: generate C program cxref(l) 

terminal, ctermid: generate file name for ctermid(3S) 

crypt, setkey, encrypt: generate hashing encryption crypt(3C) 

lexical tasks, lex: generate programs for simple lex(l) 

/srand48, seed48, lcong48: generate uniformly distributed/ drand48(3C) 

srand: simple random-number generator, rand, rand(3C) 

gets, fgets: get a string from a stream gets(3S) 

get: get a version of an SCCS file get(l) 

ulimit: get and set user limits ulimit(2) 

the user, cuserid: get character login name of cuserid(3S) 

getc, getchar, fgetc, getw: get character or word from a/ getc(3S) 

the listener, nlsgetcall: get client's data passed via nlsgetcall(3N) 

nlist: get entries from name list nlist(3C) 

umask: set and get file creation mask umask(2) 

Stat, fstat: get file status stat(2) 

statfs, fstatfs: get file system information statfs(2) 

ustat: get file system statistics ustat(2) 

information, sysfs: get file system type sysfs(2) 

file, get: get a version of an SCCS get(l) 

/setgrent, endgrent, fgetgrent: get group file entry getgrent(3C) 

getlogin: get login name getlogin(3C) 

msgget: get message queue msgget(2) 

getpw: get name from UID getpw(3C) 

system, uname: get name of current UNIX uname(2) 

provider, nlsprovider: get name of transport nlsprovider(3N) 

getmsg: get next message off a stream getmsg(2) 

unget: undo a previous get of an SCCS file unget(l) 
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argument vector, getopt: get option letter from getopt(3C) 

/setpwent, endpwent, fgetpwent: get password file entry getpwent(3C) 

working directory, getcwd: get path name of current getcwd(3C) 

times, times: get process and child process times(2) 

and/ getpid, getpgrp, getppid: get process, process group, getpid(2) 

information. t_getinfo: get protocol-specific service t_getinfo(3N) 

/geteuid, getgid, getegid: get real user, effective user,/ getuid(2) 

semget: get set of semaphores semget(2) 

identifier, shmget: get shared memory segment shmget(2) 

t_getstate: get the current state t_getstate(3N) 

time: get time time(2) 

get character or word from a/ getc, getchar, fgetc, getw: getc(3S) 

character or word from/ getc, getchar, fgetc, getw: get getc(3S) 

current working directory, getcwd: get path name of getcwd(3C) 

entries and put in a/ getdents: read directory getdents(2) 

getuid, geteuid, getgid, getegid: get real user,/ getuid(2) 

environment name, getenv: return value for getenv(3C) 

real user, effective/ getuid, geteuid, getgid, getegid: get getuid(2) 

user,/ getuid, geteuid, getgid, getegid: get real getuid(2) 

setgrent, endgrent,/ getgrent, getgrgid, getgrnam getgrent(3C) 

endgrent,/ getgrent, getgrgid, getgrnam, setgrent, getgrent(3C) 

getgrent, getgrgid, getgrnam, setgrent, endgrent,/ getgrent(3C) 

the system clock in ticks per/ gethz: return the frequency of gethz(3C) 

getlogin: get login name getiogin(3C) 

sh-eam. getmsg: get next message off a getmsg(2) 

argument vector, getopt: get option letter from getopt(3C) 

getpass: read a password getpass(3C) 

process group, and/ getpid, getpgrp, getppid: get process, getpid(2) 

process, process group, and/ getpid, getpgrp, getppid: get getpid(2) 

group, and/ getpid, getpgrp, getppid: get process, process getpid(2) 

getpw: get name from UID getpw(3C) 

setpwent, endpwent,/ getpwent, getpwuid, getpwnam, getpwent(3C) 

getpwent, getpwuid, getpwnam, setpwent, endpwent,/ getpwent(3C) 

endpwent,/ getpwent, getpwuid, getpwnam, setpwent, getpwent(3C) 

a stream, gets, fgets: get a string from gets(3S) 

and terminal settings used by getty. gettydefs: speed gettydefs(4) 

settings used by getty. gettydefs: speed and terminal gettydefs(4) 

getegid: get real user,/ gehiid, geteuid, getgid, getuid(2) 

getutiine, pututiine,/ getut: getutent, getutid, getut(3C) 

pututiine, setutent,/ getut: getutent, getutid, getutiine, getut(3C) 

setutent,/ getut: gehJtent, getutid, getutiine, puhitiine, getut(3C) 

getut: getutent, getutid, gehitline, puhitline,/ getut(3C) 

from a/ getc, getchar, fgetc, getw: get character or word getc(3S) 

ascftime,/ ctime, localtime, gmtime, asctime, cftime, ctime(3C) 

setjmp, longjmp: non-local goto setjmp(3C) 

string, format of graphical/ gps: graphical primitive gps(4) 

primitive string, format of graphical files, /graphical gps(4) 

format of graphical/ gps: graphical primitive string, gps(4) 

plot: graphics interface plot(4) 

subroutines, plot: graphics interface plot(3X) 

/user, effective user, real group, and effective group/ getuid(2) 

/getppid: get process, process group, and parent process IDs getpid(2) 

endgrent, fgetgrent: get group file entry, /setgrent, getgrent(3C) 
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group: group file group(4) 

group: group file group(4) 

setpgrp: set process group ID setpgrp(2) 

real group, and effective group IDs. /effective user, getuid(2) 

setuid, setgid: set user and group IDs setuid(2) 

chown: change owner and group of a file chown(2) 

a signal to a process or a group of processes, /send kill(2) 

update, and regenerate groups of programs, /maintain, make(l) 

ssignal, gsignal: software signals ssignal(3C) 

varargs: handle variable argument list varargs(5) 

curses: terminal screen handling and optimization/ curses(3X) 

hcreate, hdestroy: manage hash search tables, hsearch, hsearch(3C) 

setkey, encrypt: generate hashing encryption, crypt, crypt(3C) 

search tables, hsearch, hcreate, hdestroy: manage hash hsearch(3C) 

tables, hsearch, hcreate, hdestroy: manage hash search hsearch(3C) 

a XENIX object file, hdr: display selected parts of hdr(l) 

file, scnhdr: section header for a common object scnhdr(4) 

files, filehdr: file header for common object filehdr(4) 

limits: file header for/ limits(4) 

unistd: file header for symbolic constants unistd(4) 

file. Idfhread: read the file header of a common object ldfhread(3X) 

/seek to the optional file header of a common object/ ldohseek(3X) 

/read an indexed/named section header of a common object/ ldshread(3X) 

Idahread: read the archive header of a member of an/ ldahread(3X) 

layers: protocol used between host and windowing terminal/ layers(5) 

terminal, jagent: host control of windowing jagent(5) 

manage hash search tables, hsearch, hcreate, hdestroy: hsearch(3C) 

sinh, cosh, tanh: hyperbolic functions sinh(3M) 

function, hypot: EucHdean distance hypot(3M) 

i286emul: emulate 80286 i286emul(l) 

setpgrp: set process group ID setpgrp(2) 

issue: issue identification file issue(4) 

get shared memory segment identifier, shmget: shmget(2) 

what: identify SCCS files what(l) 

group, and parent process IDs. /get process, process getpid(2) 

group, and effective group IDs. /effective user, real getuid(2) 

setgid: set user and group IDs. setuid, setuid(2) 

/fpgetsticky, fpsetsticky: IEEE floating point/ fpgeti-ound(3C) 

core: format of core image file core(4) 

format of curses screen image file. scr_dump: scr_dump(4) 

pnch: file format for card images pnch(4) 

limits: file header for implementation-specific/ limits(4) 

of a/ Idtbindex: compute the index of a symbol table entry ldtbindex(3X) 

a common/ Idtbread: read an indexed symbol table entry of ldtbread(3X) 

Idshread, Idnshread: read an indexed/named section header/ ldshread(3X) 

Idsseek, Idnsseek: seek to an indexed/named section of a/ ldsseek(3X) 

receipt of an orderly release indication, /acknowledge t_rcvrel(3N) 

receive a unit data error indication. t__xcvuderr: t_rcvuderr(3N) 

terminfo descriptions, infocmp: compare or print out infocmp(lM) 

inittab: script for the init process inittab(4) 

t_sndrel: initiate an orderly release t_sndrel(3N) 

process, popen, pclose: initiate pipe to/from a popen(3S) 

process, inittab: script for the init inittab(4) 
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inode: format of an inode inode(4) 

inode: format of an inode inode(4) 

sscanf: convert formatted input, scanf, fscanf, scanf(3S) 

push character back into input stream, ungetc: ungetc(3S) 

fread, fwrite: binary input/output fread(3S) 

poll: STREAMS input/output multiplexing poll(2) 

stdio: standard buffered input/output package stdio(3S) 

fileno: stream status inquiries, /feof, clearerr, ferror(3S) 

abs: return integer absolute value abs(3C) 

/164a: convert between long integer and base-64 ASCII/ a641(3C) 

sputl, sgetl: access long integer data in a/ sputl(3X) 

atol, atoi: convert string to integer, strtol, strtol(3C) 

/ltol3: convert between 3-byte integers and long integers 13tol(3C) 

3-byte integers and long integers, /convert between 13tol(3C) 

program, cscope: interactively examine a C cscope(l) 

plot: graphics interface plot(4) 

plot: graphics interface subroutines plot(3X) 

pipe: create an interprocess channel pipe(2) 

stdipc: ftok: standard interprocess communication/ stdipc(3C) 

sleep: suspend execution for interval sleep(3C) 

formats, intro: introduction to file intro(4) 

functions and libraries, intro: introduction to intro(3) 

miscellany, intro: introduction to intro(5) 

programming commands, intro: introduction to intro(l) 

calls and error numbers, intro: introduction to system intro(2) 

intro: introduction to file formats intro(4) 

libraries, intro: introduction to functions and intro(3) 

intro: introduction to miscellany intro(5) 

commands, intro: introduction to programming intro(l) 

and error numbers, intro: introduction to system calls intro(2) 

ioctl: control device ioctl(2) 

/islower, isupper, isalpha, isalnum, isspace, iscntrl,/ ctype(3C) 

/isxdigit, islower, isupper, isalpha, isalnum, isspace,/ ctype(3C) 

/ispunct, isprint, isgraph, isascii, tolower, toupper,/ ctype(3C) 

terminal, ttyname, isatty: find name of a ttyname(3C) 

/isalpha, isalnum, isspace, iscntrl, ispunct, isprint,/ ctype(3C) 

isupper, isalpha,/ ctype: isdigit, isxdigit, islower, ctype(3C) 

/iscntrl, ispunct, isprint, isgraph, isascii, tolower,/ ctype(3C) 

ctype: isdigit, isxdigit, islower, isupper, isalpha,/ ctype(3C) 

for floating point NaN/ isnan: isnand, isnanf: test isnan(3C) 

floating point NaN/ isnan: isnand, isnanf: test for isnan(3C) 

point NaN/ isnan: isnand, isnanf: test for floating isnan(3C) 

/isspace, iscntrl, ispunct, isprint, isgraph, isascii,/ ctype(3C) 

/isalnum, isspace, iscntrl, ispunct, isprint, isgraph,/ ctype(3C) 

/isupper, isalpha, isalnum, isspace, iscntrl, ispunct,/ ctype(3C) 

system: issue a shell command system(3S) 

issue: issue identification file issue(4) 

file, issue: issue identification issue(4) 

/isdigit, isxdigit, islower, isupper, isalpha, isalnum,/ ctype(3C) 

isalpha,/ ctype: isdigit, isxdigit, islower, isupper, ctype(3C) 

item: CRT item routines item(3X) 

item: CRT item routines item(3X) 

functions, bessel: jO, jl, jn, yO, yl, yn: Bessel bessel(3M) 
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functions, bessel: jO, jl, jn, yO, yl, yn: Bessel bessel(3M) 

windowing terminal, jagent: host control of jagent(5) 

functions, bessel: jO, jl, jn, yO, yl, yn: Bessel bessel(3M) 

/lrand48, nrand48, mrand48, jrand48, srand48, seed48,/ drand48(3C) 

process or a group of/ kill: send a signal to a kill(2) 

3-byte integers and long/ 13tol, ltol3: convert between 13tol(3C) 

integer and base-64/ a641, 164a: convert between long a641(3C) 

cpp: the C language preprocessor cpp(l) 

cftime: language specific strings cftin\e(4) 

host and windowing terminal/ layers: protocol used between layers(5) 

/jrand48, srand48, seed48, lcong48: generate uniformly/ drand48(3C) 

object files. Id: link editor for common ld(l) 

object file. Idclose, Idaclose: close a common ldclose(3X) 

header of a member of an/ Idahread: read the archive ldahread(3X) 

file for reading. Idopen, Idaopen: open a common object ldopen(3X) 

common object file. Idclose, Idaclose: close a ldclose(3X) 

of floating-point/ frexp, Idexp, modf: manipulate parts frexp(3C) 

access routines. Idfcn: common object file ldfcn(4) 

of a common object file. Idfhread: read the file header ldfhread(3X) 

name for common object file/ Idgetname: retrieve symbol ldgetname(3X) 

line number entries/ Idlread, Idlinit, Idlitem: manipulate ldlread(3X) 

number/ Idlread, Idlinit, Idlitem: manipulate line ldlread(3X) 

manipulate line number/ Idlread, Idlinit, Idlitem: ldlread(3X) 

line number entries of a/ Idlseek, Idnlseek: seek to ldlseek(3X) 

entries of a section/ Idlseek, Idnlseek: seek to line number ldlseek(3X) 

entries of a section/ Idrseek, Idnrseek: seek to relocation ldrseek(3X) 

indexed/named/ Idshread, Idnshread: read an ldshread(3X) 

indexed/named/ Idsseek, Idnsseek: seek to an ldsseek(3X) 

file header of a common/ Idohseek: seek to the optional ldohseek(3X) 

object file for reading. Idopen, Idaopen: open a common ldopen(3X) 

relocation entries of a/ Idrseek, Idnrseek: seek to ldrseek(3X) 

indexed/named section header/ Idshread, Idnshread: read an ldshread(3X) 

indexed/named section of a/ Idsseek, Idnsseek: seek to an ldsseek(3X) 

of a symbol table entry of a/ Idtbindex: compute the index ldtbindex(3X) 

symbol table entry of a/ Idtbread: read an indexed ldtbread(3X) 

table of a common object/ Idtbseek: seek to the symbol ldtbseek(3X) 

getopt: get option letter from argument vector getopt(3C) 

simple lexical tasks, lex: generate programs for lex(l) 

generate programs for simple lexical tasks, lex: lex(l) 

update. Isearch, Ifind: linear search and lsearch(3C) 

introduction to functions and libraries, intro: intro(3) 

tam: TAM transition libraries tam(3C) 

chkshlib: compare shared libraries tool chkshlib(l) 

windowing terminal function library, libwindows: libwindows(3X) 

relation for an object library, /find ordering lorder(l) 

portable/ ar: archive and library maintainer for ar(l) 

mkshlib: create a shared library mkshlib(l) 

field: FIELD library routines field(3X) 

fieldtype: FIELDTYPE library routines fieldtype(3X) 

form: FORM library routines form(3X) 

panel: PANEL library routines panel(3X) 

t_alloc: allocate a library structure t_alloc(3N) 

t_free: free a library structure t_free(3N) 
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t_sync: synchronize transport library t_sync(3N) 

function library, libwindows: windowing terminal libwindows(3X) 

implementation-specific/ limits: file header for limits(4) 

ulimit: get and set user limits ulimit(2) 

establish an outgoing terminal line connection, dial: dial(3C) 

common object file, linenum: line number entries in a linenum(4) 

/Idlinit, Idlitem: manipulate line number entries of a/ , ldlread(3X) 

Idlseek, Idnlseek: seek to line number entries of a/ ldlseek(3X) 

strip: strip symbol and line number information from a/ strip(l) 

Isearch, Ifind: linear search and update lsearch(3C) 

profile data. Iprof: display line-by-line execution count lprof(l) 

in a common object file, linenum: line number entries linenum(4) 

files. Id: link editor for common object ld(l) 

a.out: common assembler and link editor output a.out(4) 

link: link to a file link(2) 

link: link to a file link(2) 

lint: a C program checker lint(l) 

nlist: get entries from name list nlist(3C) 

nm: print name list of common object file nm(l) 

by fsck and/ checklist: list of file systems processed checklist(4) 

from a common object file, list: produce C source listing list(l) 

handle variable argument list, varargs: varargs(5) 

output of a varargs argument list, /print formatted vprintf(3S) 

t_listen: listen for a connect request t_listen(3N) 

client's data passed via the listener, nlsgetcall: get nlsgetcall(3N) 

nlsrequest: format and send listener service request/ nlsrequest(3N) 

file, list: produce C source listing from a common object list(l) 

cftime, ascftime,/ ctime, localtime, gmtime, asctime, ctime(3C) 

end, etext, edata: last locations in program end(3C) 

memory, plock: lock process, text, or data in plock(2) 

files, lockf: record locking on lockf(3C) 

lockf: record locking on files lockf(3C) 

gamma: log gamma function gamma(3M) 

exponential, logarithm,/ exp, log, loglO, pow, sqrt: exp(3M) 

/usr/adm/loginlog: log of failed login attempts loginlog(4) 

logarithm, power,/ exp, log, loglO, pow, sqrt: exponential, exp(3M) 

/loglO, pow, sqrt: exponential, logarithm, power, square root/ exp(3M) 

/log of failed login attempts loginlog(4) 

getlogin:get login name getlogin(3C) 

cuserid: get character login name of the user cuserid(3S) 

logname: return login name of user logname(3X) 

setting up an environment at login time, profile: profile(4) 

user, logname: return login name of logname(3X) 

a641, 164a: convert between long integer and base-64 ASCII/ a641(3C) 

sputl, sgetl: access long integer data in a/ sputl(3X) 

between 3-byte integers and long integers. /ltol3: convert 13tol(3C) 

setjmp, longjmp: non-local goto setjmp(3C) 

for an object library, lorder: find ordering relation lorder(l) 

execution count profile data. Iprof: display line-by-line lprof(l) 

jrand48,/ drand48, erand48, lrand48, nrand48, mrand48, drand48(3C) 

and update. Isearch, Ifind: linear search lsearch(3C) 

pointer. Iseek: move read/write file lseek(2) 

integers and long/ 13tol, ltol3: convert between 3-byte 13tol(3C) 
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m4: macroprocessor m4(l) 

values: machine-dependent values values(5) 

/access long integer data in a machine-independent fashion sputl(3X) 

sysi86: machine-specific functions sysi86(2) 

m4: macroprocessor m4(l) 

malloc, free, realloc, calloc: main memory allocator malloc(3C) 

/mallopt, mallinfo: fast main memory allocator malloc(3X) 

regenerate groups of/ make: maintain, update, and make(l) 

ar: archive and library maintainer for portable/ ar(l) 

sees file, delta: make a delta (change) to an delta(l) 

mkdir: make a directory mkdir(2) 

or ordinary file or a/ mknod: make a directory or a special mknod(2) 

mktemp: make a unique file name mktemp(3C) 

regenerate groups of/ make: maintain, update, and make(l) 

/realloc, calloc, mallopt, maUinfo: fast main memory/ malloc(3X) 

main memory allocator, malloc, free, realloc, calloc: malloc(3C) 

mallopt, mallinfo: fast main/ malloc, free, realloc, calloc, malloc(3X) 

malloc, free, realloc, calloc, mallopt, mallinfo: fast main/ malloc(3X) 

/tfind, tdelete, twalk: manage binary search trees tsearch(3C) 

hsearch, hcreate, hdestroy: manage hash search tables hsearch(3C) 

endpoint. t_optmgmt: manage options for a transport t_optmgmt(3N) 

sigignore, sigpause: signal management, /sigrelse, sigset(2) 

of/ Idlread, Idlinit, Idlitem: manipulate line number entries ldlread(3X) 

frexp, Idexp, modf: manipulate parts of/ frexp(3C) 

comment section, mcs: manipulate the object file mcs(l) 

ascii: map of ASCII character set asdi(5) 

set and get file creation mask, umask: umask(2) 

File Sharing name server master file, rfmaster: Remote rfmaster(4) 

regular expression compile and match routines, regexp: regexp(5) 

math: math functions and constants math(5) 

constants, math: math functions and math(5) 

function, matherr: error-handling matherr(3M) 

file comment section, mcs: manipulate the object mcs(l) 

mdevice: file format mdevice(4) 

memcpy, memset:/ memory: memccpy, memchr, memcmp, memory(3C) 

memset:/ memory: memccpy, memchr, memcmp, memcpy, memory(3C) 

memory: memccpy, memchr, memcmp, memcpy, memset: memory/ .... memory(3C) 

/memccpy, memchr, memcmp, memcpy, memset: memory/ memory(3C) 

free, realloc, calloc: main memory allocator, malloc, malloc(3C) 

mallopt, mallinfo: fast main memory allocator, /calloc, malloc(3X) 

shmctl: shared memory control operations shmctl(2) 

memcmp, memcpy, memset:/ memory: memccpy, memchr, memory(3C) 

memcmp, memcpy, memset: memory operations, /memchr, memory(3C) 

shmop: shmat, shmdt: shared memory operations shmop(2) 

lock process, text, or data in memory, plock: plock(2) 

shmget: get shared memory segment identifier shmget(2) 

/memchr, memcmp, memcpy, memset: memory operations memory(3C) 

menu: CRT menu routines menu(3X) 

menu: CRT menu routines menu(3X) 

msgctl: message control operations msgctl(2) 

send listener service request message, /format and nlsrequest(3N) 

getmsg: get next message off a stream getmsg(2) 

putmsg: send a message on a stream putmsg(2) 
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msgop: msgsnd, msgrcv: message operations msgop(2) 

msgget: get message queue msgget(2) 

t_error: produce error message t_error(3N) 

sys_nerr: system error messages, /ermo, sys_errlist, perror(3C) 

mfsys: file format mfsys(4) 

mkdir: make a directory mkdir(2) 

special or ordinary file or a/ mknod: make a directory or a mknod(2) 

library, mkshlib: create a shared mkshlib(l) 

name, mktemp: make a unique file mktemp(3C) 

table, mnttab: mounted file system mnttab(4) 

chmod: change mode of file chmod(2) 

floating-point/ frexp, Idexp, modf: manipulate parts of frexp(3C) 

utime: set file access and modification times utime(2) 

profile, monitor: prepare execution monitor(3C) 

mount: mount a file system mount(2) 

mount: mount a file system mount(2) 

mnttab: mounted file system table mnttab(4) 

Iseek: move read/ write file pointer lseek(2) 

/erand48, lrand48, nrand48, mrand48, jrand48, srand48,/ drand48(3C) 

operations, msgctl: message control msgctl(2) 

msgget: get message queue msgget(2) 

operations, msgop: msgsnd, msgrcv: message msgop(2) 

msgop: msgsnd, msgrcv: message operations msgop(2) 

operations, msgop: msgsnd, msgrcv: message msgop(2) 

mtune: file format mtune(4) 

used by xt(7)/ xtproto: multiplexed channels protocol xtproto(5) 

poll: STREAMS input/output multiplexing poll(2) 

test for floating point NaN (Not-A-Number). /isnanf: isnan(3C) 

systems processed by fsck and ncheck. /list of file checklist(4) 

process, nice: change priority of a nice(2) 

list, nlist: get entries from name nlist(3C) 

passed via the listener, nlsgetcall: get client's data nlsgetcall(3N) 

transport provider, nlsprovider: get name of nlsprovider{3N) 

listener service request/ nlsrequest: format and send nlsrequest(3N) 

object file, nm: print name list of common nm(l) 

setjmp, longjmp: non-local goto setjmp(3C) 

test for floating point NaN (Not-A-Number). /isnanf: isnan(3C) 

drand48, erand48, lrand48, nrand48, mrand48, jrand48,/ drand48(3C) 

dis: object code disassembler dis(l) 

Idfcn: common object file access routines ldfcn(4) 

mcs: manipulate the object file comment section mcs(l) 

conv: common object file converter conv(l) 

cprs: compress a common object file cprs(l) 

dump selected parts of an object file, dump: dump(l) 

Idopen, Idaopen: open a common object file for reading ldopen(3X) 

number entries of a common object file function, /line ldlread(3X) 

selected parts of a XENIX object file, hdr: display hdr(l) 

Idaclose: close a common object file. Idclose, ldclose(3X) 

the file header of a common object file. Idfhread: read ldfhread(3X) 

of a section of a common object file, /number entries ldlseek(3X) 

file header of a common object file, /to the optional ldohseek(3X) 

of a section of a common object file, /entries ldrseek(3X) 

section header of a common object file, /indexed/named ldshread(3X) 
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section of a common object file, /indexed/named ldsseek(3X) 

symbol table entry of a common object file, /the index of a ldtbindex(3X) 

symbol table entry of a common object file, /read an indexed ldtbread(3X) 

the symbol table of a common object file, /seek to ldtbseek(3X) 

number entries in a common object file, linenum: line linenum(4) 

C source listing from a common object file, list: produce list(l) 

nm: print name list of common object file nm(l) 

information for a common object file, /relocation reloc(4) 

section header for a common object file, scnhdr: scnhdr(4) 

the printable strings in an object file, strings: find strings(l) 

information from a common object file, /and line number strip(l) 

entry, /symbol name for common object file symbol table ldgetname(3X) 

format, syms: common object file symbol table syms(4) 

file header for common object files, filehdr: filehdr(4) 

Id: link editor for common object files ld(l) 

sizes in bytes of common object files, /print section size(l) 

find ordering relation for an object library, lorder: lorder(l) 

reading. Idopen, Idaopen: open a common object file for ldopen(3X) 

fopen, freopen, fdopen: open a stream fopen(3S) 

dup: duplicate an open file descriptor dup{2) 

dup2: duplicate an open file descriptor dup2(3C) 

open: open for reading or writing open(2) 

writing, open: open for reading or open(2) 

seekdir,/ directory: opendir, readdir, telldir, directory(3C) 

rewinddir, closedir: directory operations, /telldir, seekdir, directory(3C) 

memcmp, memcpy, memset: memory operations, /memccpy, memchr, memory(3C) 

msgctl: message control operations msgcti(2) 

msgop: msgsnd, msgrcv: message operations msgop(2) 

semcti: semaphore control operations semcti(2) 

semop: semaphore operations semop(2) 

shmcti: shared memory control operations shmcti(2) 

shmat, shmdt: shared memory operations, shmop: shmop(2) 

strcspn, strtok: string operations, /strpbrk, strspn, string(3C) 

terminal screen handling and optimization package, curses: curses(3X) 

vector, getopt: get option letter from argument getopt(3C) 

common/ Idohseek: seek to the optional file header of a ldohseek(3X) 

fcnti: file conhrol options fcnti(5) 

endpoint. t_optmgmt: manage options for a ti-ansport t_optii\gmt(3N) 

object library, lorder: find ordering relation for an lorder(l) 

/acknowledge receipt of an orderly release indication t_rcvrel(3N) 

L_sndrel: initiate an orderly release t_sndrel(3N) 

a directory or a special or ordinary file or a FIFO, /make mknod(2) 

dial: establish an outgoing terminal line/ dial(3C) 

assembler and link editor output, a.out: common a.out(4) 

/vsprintf: print formatted output of a varargs argument/ vprintf(3S) 

sprintf: print formatted output, printf, fprintf, printf(3S) 

chown: change owner and group of a file chown(2) 

handling and optimization package, /terminal screen curses(3X) 

standard buffered input/output package, stdio: stdio(3S) 

interprocess communication package, /ftok: standard stdipc(3C) 

panel: PANEL library routines panel(3X) 

panel: PANEL library routines panel(3X) 

process, process group, and parent process IDs. /get getpid(2) 
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nlsgetcall: get client's data passed via the listener nlsgetcall(3N) 

passwd: password file passwd(4) 

functions, crypt: password and file encryption crypt(3X) 

/endpwent, fgetpwent: get password file entry getpwent(3C) 

putpwent: write password file entry putpwent(3C) 

passwd: password file passwd(4) 

getpass: read a password getpass(3C) 

directory, getcwd: get path name of current working getcwd(3C) 

signal, pause: suspend process until pause(2) 

a process, popen, pclose: initiate pipe to/from popen(3S) 

format, acct: per-process accounting file acct(4) 

sys__nerr: system error/ perror, ermo, sys_errlist, perror(3C) 

channel, pipe: create an interprocess pipe(2) 

popen, pclose: initiate pipe to/from a process popen(3S) 

data in memory, plock: lock process, text, or plock(2) 

plot: graphics interface plot(4) 

subroutines, plot: graphics interface plot(3X) 

images, pnch: file format for card pnch(4) 

ftell: reposition a file pointer in a stream, /rewind, fseek(3S) 

Iseek: move read/write file pointer lseek(2) 

multiplexing, poll: STREAMS input/output poll(2) 

to/from a process, popen, pclose: initiate pipe popen(3S) 

and library maintainer for portable archives, /archive ar(l) 

logarithm,/ exp, log, loglO, pow, sqrt: exponential, exp(3M) 

/sqrt: exponential, logarithm, power, square root functions exp(3M) 

monitor: prepare execution profile monitor(3C) 

cpp: the C language preprocessor cpp(l) 

unget: undo a previous get of an SCCS file unget(l) 

graphical/ gps: graphical primitive string, format of gps(4) 

types: primitive system data types types(5) 

prs: print an SCCS file prs(l) 

editing activity, sact: print current SCCS file sact(l) 

vprintf, vfprintf, vsprintf: print formatted output of a/ vprintf(3S) 

printf, fprintf, sprintf: print formatted output printf(3S) 

object file, nm: print name list of common nm(l) 

infocmp: compare or print out terminfo/ infocmp(lM) 

of common object files, size: print section sizes in bytes size(l) 

file, strings: find the printable strings in an object strings(l) 

print formatted output, printf, fprintf, sprintf: printf(3S) 

nice: change priority of a process nice(2) 

acct: enable or disable process accounting acct(2) 

alarm: set a process alarm clock alarm(2) 

times, times: get process and child process times(2) 

exit, —exit: terminate process exit(2) 

fork: create a new process fork(2) 

/getpgrp, getppid: get process, process group, and parent/ getpid(2) 

setpgrp: set process group ID setpgrp(2) 

process group, and parent process IDs. /get process, getpid(2) 

inittab: script for the init process inittab(4) 

nice: change priority of a process nice(2) 

kill: send a signal to a process or a group of/ kill(2) 

initiate pipe to/from a process, popen, pclose: popen(3S) 

getpid, getpgrp, getppid: get process, process group, and/ getpid(2) 
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memory, plock: lock process, text, or data in plock(2) 

times: get process and child process times times(2) 

wait: wait for child process to stop or terminate wait(2) 

ptrace: process trace ptrace(2) 

pause: suspend process until signal pause(2) 

/list of file systems processed by fsck and ncheck checklist(4) 

to a process or a group of processes, /send a signal kill(2) 

a common object file, list: produce C source listing from list(l) 

t_error: produce error message t_error(3N) 

prof: display profile data prof(l) 

function, prof: profile within a prof(5) 

profile, profil: execution time profil(2) 

line-by-line execution count profile data. Iprof: display lprof(l) 

prof: display profile data prof(l) 

monitor: prepare execution profile monitor(3C) 

profil: execution time profile profil(2) 

environment at login time, profile: setting up an profile(4) 

prof: profile within a function prof(5) 

intro: introduction to programming commands intro(l) 

windowing terminal/ layers: protocol used between host and layers(5) 

xtproto: multiplexed channels protocol used by xt(7) driver xtproto(5) 

information. t_getinfo: get protocol-specific service t_getinfo(3N) 

get name of transport provider, nlsprovider: nlsprovider(3N) 

prs: print an SCCS file prs(l) 

/generate uniformly distributed pseudo-random numbers drand48(3C) 

ptrace: process trace ptrace(2) 

stream, ungetc: push character back into input ungetc(3S) 

put character or word on a/ putc, putchar, fputc, putw: putc(3S) 

character or word on a/ putc, putchar, fputc, putw: put putc(3S) 

environment, putenv: change or add value to putenv(3C) 

stream, putmsg: send a message on a putmsg(2) 

entry, putpwent: write password file putpwent(3C) 

stream, puts, fputs: put a string on a puts(3S) 

/getutent, getutid, getutline, pututline, setutent, endutent,/ getut(3C) 

a/ putc, putchar, fputc, putw: put character or word on putc(3S) 

qsort: quicker sort qsort(3C) 

msgget: get message queue msgget(2) 

qsort: quicker sort qsort(3C) 

random-number generator, rand, srand: simple rand(3C) 

rand, srand: simple random-number generator rand(3C) 

getpass: read a password getpass(3C) 

entry of a common/ Idtbread: read an indexed symbol table ldtbread(3X) 

header/ Idshread, Idnshread: read an indexed/named section ldshread(3X) 

in a/ getdents: read directory entries and put getdents(2) 

read: read from file read(2) 

read: read from file read(2) 

member of an/ Idahread: read the archive header of a ldahread(3X) 

common object file, Idfhread: read the file header of a ldfhread(3X) 

directory: opendir, readdir, telldir, seekdir,/ directory(3C) 

open a common object file for reading. Idopen, Idaopen: ldopen(3X) 

open: open for reading or writing open(2) 

Iseek: move read/write file pointer lseek(2) 

allocator, malloc, free, realloc, calloc: main memory malloc(3C) 
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mallinfo: fast/ malloc, free, realloc, calloc, mallopt, malloc(3X) 

specify what to do upon receipt of a signal, signal: signal(2) 

t__rcvrel: acknowledge receipt of an orderly release/ t_rcvrel(3N) 

t_rcvudata: receive a data unit t_rcvudata(3N) 

indication. t_rcvuderr: receive a unit data error t_rcvuderr(3N) 

sent over a/ t_rcv: receive data or expedited data t_rcv(3N) 

a connect/ t_rcvconnect: receive the confirmation from t_rcvconnect(3) 

lockf: record locking on files lockf(3C) 

execute regular expression, regcmp, regex: compile and regcmp(3X) 

compile, regcmp: regular expression regcmp(l) 

make: maintain, update, and regenerate groups of programs make(l) 

regular expression, regcmp, regex: compile and execute regcmp(3X) 

compile and match routines, regexp: regular expression regexp(5) 

match routines, regexp: regular expression compile and regexp(5) 

regcmp: regular expression compile regcmp(l) 

regex: compile and execute regular expression, regcmp, regcmp(3X) 

lorder: find ordering relation for an object/ lorder(l) 

/receipt of an orderly release indication t_rcvrel(3N) 

t_sndrel: initiate an orderly release t_sndrel(3N) 

for a common object file, reloc: relocation information reloc(4) 

Idrseek, Idnrseek: seek to relocation entries of a/ ldrseek(3X) 

common object file, reloc: relocation information for a reloc(4) 

/fmod, fabs: floor, ceiling, remainder, absolute value/ floor(3M) 

server master file, rfmaster: Remote File Sharing name rfmaster(4) 

file, rmdel: remove a delta from an SCCS rmdel(l) 

rmdir: remove a directory rmdir(2) 

unlink: remove directory entry unlink(2) 

clock: report CPU time used clock(3C) 

stream, fseek, rewind, ftell: reposition a file pointer in a fseek(3S) 

and send listener service request message, /format nlsrequest(3N) 

t__accept: accept a connect request t__accept(3N) 

t—listen: listen for a connect request t_listen(3N) 

confirmation from a connect request, /receive the t_rcvconnect(3) 

send user-initiated disconnect request. t_snddis: t_snddis(3N) 

disconnect. t_rcvdis: retrieve information from t_rcvdis(3N) 

common object file/ Idgetname: retrieve symbol name for ldgetname(3X) 

abs: return integer absolute value abs(3C) 

logname: return login name of user logname(3X) 

system clock in ticks/ gethz: return the frequency of the gethz(3C) 

name, getenv: return value for environment getenv(3C) 

Stat: data returned by stat system call stat(5) 

file pointer in a/ fseek, rewind, ftell: reposition a fseek(3S) 

-/readdir, telldir, seekdir, rewinddir, dosedir: directory/ directory(3C) 

creat: create a new file or rewrite an existing one creat(2) 

name server master file, rfmaster: Remote File Sharing rfmaster(4) 

SCCS file, rmdel: remove a delta from an rmdel(l) 

rmdir: remove a directory rmdir(2) 

chroot: change root directory chroot(2) 

logarithm, power, square root functions, /exponential, exp(3M) 

field: FIELD library routines field(3X) 

fieldtype: FIELDTYPE library routines fieldtype(3X) 

form: FORM library routines form(3X) 

item: CRT item routines item(3X) 
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common object file access routines. Idfcn: ldfcn(4) 

menu: CRT menu routines menu(3X) 

panel: PANEL library routines panel(3X) 

expression compile and match routines, regexp: regular regexp(5) 

editing activity, sact: print current SCCS file sact(l) 

space allocation, brk, sbrk: change data segment brk(2) 

formatted input, scanf, fscanf, sscanf: convert scanf(3S) 

the delta commentary of an SCCS delta, cdc: change cdc(l) 

comb: combine SCCS deltas comb(l) 

make a delta (change) to an SCCS file, delta: delta(l) 

sact: print current SCCS file editing activity sact(l) 

get: get a version of an SCCS file get(l) 

prs: print an SCCS file prs(l) 

rmdel: remove a delta from an SCCS file rmdel(l) 

compare two versions of an SCCS file, sccsdiff: sccsdiff(l) 

sccsfile: format of SCCS file. sccsfile(4) 

undo a previous get of an SCCS file, unget: unget(l) 

val: validate SCCS file val(l) 

admin: create and administer SCCS files admin(l) 

what: identify SCCS files what(l) 

of an SCCS file, sccsdiff: compare two versions sccsdiff (1) 

sccsfile: format of SCCS file sccsfile(4) 

common object file, scnhdr: section header for a scnhdr(4) 

screen image file. scr_dump: format of curses scr_dump(4) 

optimization/ curses: terminal screen handling and curses(3X) 

scr_dump: format of curses screen image file scr_dump(4) 

inittab: script for the init process inittab(4) 

sdb: symbolic debugger sdb(l) 

sdevice: file format sdevice(4) 

bsearch: binary search a sorted table bsearch(3C) 

Isearch, Ifind: linear search and update lsearch(3C) 

hcreate, hdestroy: manage hash search tables, hsearch, hsearch(3C) 

tdelete, twalk: manage binary search trees, tsearch, tfind, tsearch(3C) 

object file, scnhdr: section header for a common scnhdr(4) 

object/ /read an indexed/named section header of a common ldshread(3X) 

the object file comment section, mcs: manipulate mcs(l) 

/to line number entries of a section of a common object/ ldlseek(3X) 

/to relocation entries of a section of a common object/ ldrseek(3X) 

/seek to an indexed/named section of a common object/ ldsseek(3X) 

common object/ size: print section sizes in bytes of size(l) 

/mrand48, jrand48, srand48, seed48, lcong48: generate/ drand48(3C) 

section of/ Idsseek, Idnsseek: seek to an indexed/named ldsseek(3X) 

a section/ Idlseek, Idnlseek: seek to line number entries of ldlseek(3X) 

a section/ Idrseek, Idnrseek: seek to relocation entries of ldrseek(3X) 

header of a common/ Idohseek: seek to the optional file ldohseek(3X) 

common object file. Idtbseek: seek to the symbol table of a ldtbseek(3X) 

/opendir, readdir, telldir, seekdir, rewinddir, closedir:/ directory(3C) 

shmget: get shared memory segment identifier shmget(2) 

brk, sbrk: change data segment space allocation brk(2) 

object file, hdr: display selected parts of a XENIX hdr(l) 

file, dump: dump selected parts of an object dump(l) 

semcti: semaphore control operations semcti(2) 

semop: semaphore operations semop(2) 
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semget: get set of semaphores ^ semget(2) 

operations, semctl: semaphore control semctl(2) 

semget: get set of semaphores semget(2) 

semop: semaphore operations semop(2) 

t_sndudata: send a data unit t_sndudata(3N) 

putmsg: send a message on a stream putmsg(2) 

a group of processes, kill: send a signal to a process or kill(2) 

over a connection. t_snd: send data or expedited data t_snd(3N) 

nlsrequest: format and send listener service request/ nlsrequest(3N) 

request. t__snddis: send user-initiated disconnect t__snddis(3N) 

/receive data or expedited data sent over a connection t_rcv(3N) 

Remote File Sharing name server master file, rfmaster: rfmaster(4) 

buffering to a stream, setbuf, setvbuf: assign setbuf(3S) 

/toascci, —tolower, _toupper, setchrclass: character hand ctype(3C) 

IDs. setuid, setgid: set user and group setuid(2) 

getgrent, getgrgid, getgmam, setgrent, endgrent, fgetgrent:/ getgrent(3C) 

goto, setjmp, longjmp: non-local setjmp(3C) 

hashing encryption, crypt, setkey, encrypt: generate crypt(3C) 

setpgrp: set process group ID setpgrp(2) 

getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent:/ getpwent(3C) 

login time, profile: setting up an environment at profile(4) 

gettydefs: speed and terminal settings used by getty gettydefs(4) 

group IDs. setuid, setgid: set user and setuid(2) 

/getutid, getutline, pututline, setutent, endutent, utmpname:/ getut(3C) 

stream, setbuf, setvbuf: assign buffering to a setbuf(3S) 

sfsys: file format sfsys(4) 

data in a/ sputl, sgetl: access long integer sputl(3X) 

chkshlib: compare shared libraries tool chkshlib(l) 

mkshlib: create a shared library mkshlib(l) 

operations, shmctl: shared memory control shmctl(2) 

shmop: shmat, shmdt: shared memory operations shmop(2) 

identifier, shmget: get shared memory segment shmget(2) 

file, rfmaster: Remote File Sharing name server master rfmaster(4) 

system: issue a shell command system(3S) 

operations, shmop: shmat, shmdt: shared memory shmop(2) 

operations, shmcd: shared memory control shmctl(2) 

operations, shmop: shmat, shmdt: shared memory shmop(2) 

segment identifier, shmget: get shared memory shmget(2) 

memory operations, shmop: shmat, shmdt: shared shmop(2) 

sigpause: signal/ sigset, sighold, sigrelse, sigignore, sigset(2) 

sigset, sighold, sigrelse, sigignore, sigpause: signal/ sigset(2) 

sigrelse, sigignore, sigpause: signal management, /sighold, sigset(2) 

pause: suspend process until signal pause(2) 

what to do upon receipt of a signal, signal: specify signal(2) 

upon receipt of a signal, signal: specify what to do signal(2) 

of processes, kill: send a signal to a process or a group kill(2) 

ssignal, gsignal: software signals ssignal(3C) 

/sighold, sigrelse, sigignore, sigpause: signal management sigset(2) 

signal/ sigset, sighold, sigrelse, sigignore, sigpause: * . . sigset(2) 

sigignore, sigpause: signal/ sigset, sighold, sigrelse, sigset(2) 

lex: generate programs for simple lexical tasks lex(l) 

generator, rand, srand: simple random-number rand(3C) 

atan, atan2:/ trig: sin, cos, tan, asin, acos, trig(3M) 
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functions. 




.... sinh(3M) 


bytes of common object files. 






object/ size: print section 






interval. 




.... sleep(3C) 


current/ ttyslot: find the 






ssignal, gsignal: 






qsort: quicker 






tsort: topological 






bsearch: binary search a 






object file, list: produce C 




. . . . list(l) 


brk, sbrk: change data segment 




.... brk(2) 


cftime: language 






fspec: format 






receipt of a signal, signal: 




.... signal(2) 


used by getty. gettydefs: 






output, printf, fprintf, 






integer data in a/ 




.... spuri(3X) 


power,/ exp, log, loglO, pow. 




.... exp(3M) 


exponential, logarithm, power. 




.... exp(3M) 


generator, rand. 




.... rand(3C) 


/nrand48, mrand48, jrand48. 




.... drand48(3C) 


input, scanf, fscanf. 






signals. 






package, stdio: 






communication/ stdipc: ftok: 




.... stdipc(3C) 


system call. 










.... stat(2) 


Stat: data returned by 






system information. 






ustat: get file system 






feof, clearerr, fileno: stream 






Stat, fstat: get file 






input/output package. 




.... stdio(3S) 


interprocess communication/ 










.... stime(2) 


wait for child process to 




.... wait(2) 


strcmp, stmcmp,/ string: 






/strcpy, stmcpy, strlen, 






/strcat, strdup, stmcat. 






/stmcat, strcmp, shucmp. 






/strrchr, strpbrk, strspn. 






stmcmp,/ string: strcat. 






fflush: close or flush a 




.... fclose(3S) 


fopen, freopen, fdopen: open a 






reposition a file pointer in a 


stream, fseek, rewind, ftell: 


.... fseek(3S) 


get character or word from a 




.... getc(3S) 


getmsg: get next message off a 






fgets: get a string from a 




.... gets(3S) 


put character or word on a 






putmsg: send a message on a 






puts, fputs: put a string on a 






setvbuf: assign buffering to a 






/feof, clearerr, fileno: 
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push character back into input stream, ungetc: ungetc(3S) 

multiplexing, poll: STREAMS input/output poll(2) 

long integer and base-64 ASCII string. /164a: convert between a641(3C) 

convert date and time to string, /ascftime, tzset: ctime(3C) 

floating-point number to string, /fcvt, gcvt: convert ecvt(3C) 

gps: graphical primitive string, format of graphical/ gps(4) 

gets, fgets: get a string from a stream gets(3S) 

puts, fputs: put a string on a stream puts(3S) 

strspn, strcspn, strtok: string operations, /strpbrk, string(3C) 

stmcat, strcmp, stmcmp,/ string: strcat, strdup, string(3C) 

number, strtod, atof: convert string to double-precision strtod(3C) 

strtol, atol, atoi: convert string to integer strtol(3C) 

cftime: language specific strings cftime(4) 

strings in an object file, strings: find the printable strings(l) 

strings: find the printable strings in an object file strings(l) 

number information from a/ strip: strip symbol and line strip(l) 

information from a/ strip: strip symbol and line number strip(l) 

/stmcmp, strcpy, stmcpy, strlen, strchr, strrchr,/ string(3C) 

string: strcat, strdup, stmcat, strcmp, stmcmp,/ string(3C) 

/strdup, stmcat, strcmp, stmcmp, strcpy, stmcpy,/ string(3C) 

/strcmp, stmcmp, strcpy, stmcpy, strlen, strchr,/ string(3C) 

/strlen, strchr, strrchr, strpbrk, strspn, strcspn,/ string(3C) 

/stmcpy, strlen, strchr, strrchr, strpbrk, strspn,/ string(3C) 

/strchr, strrchr, strpbrk, strspn, strcspn, strtok:/ string(3C) 

to double-precision number, strtod, atof: convert string strtod(3C) 

/strpbrk, strspn, strcspn, strtok: string operations string(3C) 

string to integer, strtol, atol, atoi: convert strtol(3C) 

t_alloc: allocate a library stmcture t_alloc(3N) 

t_free: free a library structure t_free(3N) 

stune: file format stune(4) 

plot: graphics interface subroutines plot(3X) 

sync: update super block sync(2) 

interval, sleep: suspend execution for sleep(3C) 

pause: suspend process until signal pause(2) 

swab: swap bytes swab(3C) 

swab: swap bytes swab(3C) 

information from/ strip: strip symbol and line number strip(l) 

file/ Idgetname: retrieve symbol name for common object ldgetname(3X) 

name for common object file symbol table entry, /symbol ldgetname(3X) 

object/ /compute the index of a symbol table entry of a common ldtbindex(3X) 

Idtbread: read an indexed symbol table entry of a common/ ldtbread(3X) 

syms: common object file symbol table format syms(4) 

object/ Idtbseek: seek to the symbol table of a common ldtbseek(3X) 

unistd: file header for symbolic constants unistd(4) 

sdb: symbolic debugger sdb(l) 

symbol table format, syms: common object file syms(4) 

sync: update super block sync(2) 

t_sync: synchronize transport library t_sync(3N) 

error/ perror, ermo, sys_errlist, sys_nerr: system perror(3C) 

information, sysfs: get file system type sysfs(2) 

functions. sysi86: machine-specific sysi86(2) 

perror, ermo, sys_errlist, sys_nerr: system error/ perror(3C) 

binary search a sorted table, bsearch: bsearch(3C) 
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for common object file symbol table entry, /symbol name ldgetname(3X) 

/compute the index of a symbol table entry of a common object/ ldtbindex(3X) 

file, /read an indexed symbol table entry of a common object ldtbread(3X) 

common object file symbol table format, syms: syms(4) 

mnttab: mounted file system table mnttab(4) 

Idtbseek: seek to the symbol table of a common object file ldtbseek(3X) 

hdestroy: manage hash search tables, hsearch, hcreate, hsearch(3C) 

request. t_accept: accept a connect t__accept(3N) 

ctags: create a tags file ctags(l) 

structure. t_alloc: allocate a library t_alloc(3N) 

tam: TAM transition libraries tam(3C) 

tam: TAM transition libraries tam(3C) 

trigonometric/ trig: sin, cos, tan, asin, acos, atan, atan2: trig(3M) 

sinh, cosh, tanh: hyperbolic functions sinh(3M) 

programs for simple lexical tasks, lex: generate lex(l) 

transport endpoint. t_bind: bind an address to a t_bind(3N) 

endpoint. t_close: close a transport t_close(3N) 

connection with another/ t_connect: establish a t_connect(3N) 

search trees, tsearch, tfind, tdelete, twalk: manage binary tsearch(3C) 

directory: opendir, readdir, telldir, seekdir, rewinddir,/ directory(3C) 

temporary file, tmpnam, tempnam: create a name for a tmpnam(3S) 

tmpfile: create a temporary file tmpfile(3S) 

tempnam: create a name for a temporary file, tmpnam, tmpnam(3S) 

terminals, term: conventional names for term(5) 

term: format of compiled term file term(4) 

file, term: format of compiled term term(4) 

terminfo: terminal capability data base terminfo(4) 

generate file name for terminal, ctermid: ctermid(3S) 

libwindows: windowing terminal function library libwindows(3X) 

host control of windowing terminal, jagent: jagent(5) 

dial: establish an outgoing terminal line connection dial(3C) 

optimization package, curses: terminal screen handling and curses(3X) 

getty. gettydefs: speed and terminal settings used by gettydefs(4) 

isatty: find name of a terminal, ttyname, ttyname(3C) 

between host and windowing terminal under, /protocol used layers(5) 

term: conventional names for terminals term(5) 

exit, —exit: terminate process exit(2) 

for child process to stop or terminate, wait: wait wait(2) 

tic: terminfo compiler tic(lM) 

infocmp: compare or print out terminfo descriptions infocmp(lM) 

data base, terminfo: terminal capability terminfo(4) 

message. t_error: produce error t_error(3N) 

isnan: isnand, isnanf: test for floating point NaN/ isnan(3C) 

fspec: format specification in text files fspec(4) 

plock: lock process, text, or data in memory plock(2) 

binary search trees, tsearch, tfind, tdelete, twalk: manage tsearch(3C) 

structure. t_free: free a library t_free(3N) 

protocol-specific service/ t_gefinfo: get t_getinfo(3N) 

state. t_getstate: get the current t_getstate(3N) 

tie: terminfo compiler tic(lM) 

of the system clock in ticks per second, /frequency gethz(3C) 

time: get time time(2) 

profil: execution time profile profil(2) 
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up an environment at login time, profile: setting profile(4) 

stime: set time stime(2) 

rime: get rime time(2) 

tzset: convert date and rime to shring. /ascftime, crime(3C) 

clock: report CPU rime used clock(3C) 

timezone: set default system time zone rimezone(4) 

process times, rimes: get process and child rimes(2) 

get process and child process rimes, rimes: times(2) 

file access and modificarion rimes, urime: set urime(2) 

rime zone, rimezone: set default system rimezone(4) 

request. t_listen: listen for a connect t_listen(3N) 

event on a transport/ t_look: look at the current t_look(3N) 

file, tmpfile: create a temporary tmpfile(3S) 

for a temporary file, rinpnam, tempnam: create a name tmpnam(3S) 

/isascii, tolower, toupper, toascci, _tolower, _toupper,/ ctype(3C) 

popen, pclose: iniriate pipe to/from a process popen(3S) 

tolower, toupper, toascci, _tolower, _toupper,/ /isascii, ctype(3C) 

/isprint, isgraph, isascii, tolower, toupper, toascd,/ ctype(3C) 

compare shared libraries tool, chkshlib: chkshlib(l) 

endpoint. t_open: establish a transport t_open(3N) 

tsort: topological sort tsort(l) 

a transport endpoint. t_optmgmt: manage options for t_optmgmt(3N) 

/toupper, toascci, _tolower, _toupper, setchrclass:/ ctype(3C) 

/isgraph, isascii, tolower, toupper, toascci, _tolower,/ ctype(3C) 

ptrace: process trace ptrace(2) 

tam: TAM transition libraries tam(3C) 

t_bind: bind an address to a transport endpoint t_bind(3N) 

t_close: close a transport endpoint t_close(3N) 

look at the current event on a transport endpoint. t_look: t_Jook(3N) 

t_open: establish a transport endpoint t_open(3N) 

/manage options for a transport endpoint t_optmgmt(3N) 

t_unbind: disable a transport endpoint t_unbind(3N) 

t_sync: synchronize transport library t_sync(3N) 

nlsprovider: get name of transport provider nlsprovider(3N) 

a connection with another transport user, /establish t_connect(3N) 

expedited data sent over a/ t_rcv: receive data or t_rcv(3N) 

confirmation from a connect/ t_rcvconnect: receive the t_rcvconnect(3) 

from disconnect. t_rcvdis: retiieve information t_rcvdis(3N) 

of an orderly release/ t_rcvrel: acknowledge receipt t_rcvrel(3N) 

unit. t_rcvudata: receive a data t__rcvudata(3N) 

data error indication. t_rcvuderr: receive a unit t_rcvuderr(3N) 

ftw: walk a file tree ftw(3C) 

twalk: manage binary search h-ees. /tfind, tdelete, tsearch(3C) 

acos, atan, atan2:/ trig: sin, cos, tan, asin, trig(3M) 

tan, asin, acos, atan, atan2: trigonometric functions, /cos, trig(3M) 

twalk: manage binary search/ tsearch, tfind, tdelete, tsearch(3C) 

data over a connection. t_snd: send data or expedited t_snd(3N) 

disconnect request. L_snddis: send user-initiated t_snddis(3N) 

release. t_sndrel: initiate an orderly t_sndrel(3N) 

t_sndudata: send a data unit t_sndudata(3N) 

tsort: topological sort tsort(l) 

library. t__sync: synchronize h-ansport t_sync(3N) 

a terminal, ttyname, isatty: find name of ttyname(3C) 
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utmp file of the current/ ttyslot: find the slot in the ttyslot(3C) 

endpoint. t_unbind: disable a transport t_unbind(3N) 

tsearch, tfind, tdelete, twalk: manage binary search/ tsearch(3C) 

sysfs: get file system type information sysfs(2) 

types, types: primitive system data types(5) 

types: primitive system data types types(5) 

to/ /asctime, cftime, ascftime, tzset: convert date and time ctime(3C) 

control, uadmin: administrative uadmin(2) 

getpw: get name from UID getpv^(3C) 

limits, ulimit: get and set user ulimit(2) 

creation mask, umask: set and get file umask(2) 

umount: unmount a file system umount(2) 

UNIX system, uname: get name of current uname(2) 

file, unget: undo a previous get of an SCCS unget(l) 

an SCCS file, unget: undo a previous get of unget(l) 

into input stream, ungetc: push character back ungetc(3S) 

/seed48, lcong48: generate uniformly distributed/ drand48(3C) 

mktemp: make a unique file name mktemp(3C) 

symbolic constants, unistd: file header for unistd(4) 

t_rcvuderr: receive a unit data error indication t_rcvuderr(3N) 

t_rcvudata: receive a data unit t_rcvudata(3N) 

t__sndudata: send a data unit t_sndudata(3N) 

entry, unlink: remove directory unlink(2) 

umount: unmount a file system umount(2) 

of programs, make: maintain, update, and regenerate groups make(l) 

Ifind: linear search and update. Isearch, lsearch(3C) 

sync: update super block sync(2) 

setuid, setgid: set user and group IDs setuid(2) 

character login name of the user, cuserid: get cuserid(3S) 

/getgid, getegid: get real user, effective user, real/ getuid(2) 

environ: user environment environ(5) 

ulimit: get and set user limits ulimit(2) 

logname: return login name of user logname(3X) 

/get real user, effective user, real group, and/ getuid(2) 

with another transport user, /establish a connection t_connect(3N) 

the utmp file of the current user, /find the slot in ttyslot(3C) 

request. t_snddis: send user-initiated disconnect t_snddis(3N) 

failed login attempts, /usr/adm/loginlog: log of loginlog(4) 

statistics, ustat: get file system ustat(2) 

modification times, utime: set file access and utime(2) 

utmp, wtmp: utmp and wtmp entry formats utmp(4) 

endutent, utmpname: access utmp file entry, /setutent, getut(3C) 

ttyslot: find the slot in the utmp file of the current user ttyslot(3C) 

entry formats, utmp, wtmp: utmp and wtmp utmp(4) 

/pututline, setutent, endutent, utmpname: access utmp file/ getut(3C) 

val: validate SCCS file val(l) 

val: validate SCCS file val(l) 

abs: return integer absolute value abs(3C) 

getenv: return value for environment name getenv(3C) 

ceiling, remainder, absolute value functions, /fabs: floor, floor(3M) 

putenv: change or add value to environment putenv(3C) 

values, values: machine-dependent values(5) 

values: machine-dependent values values(5) 
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/print formatted output of a varargs argument list vprintf(3S) 

argument list, varargs: handle variable varargs(5) 

varargs: handle variable argument list varargs(5) 

vc: version control vc(l) 

option letter from argument vector, getopt: get getopt(3C) 

assert: verify program assertion assert(3X) 

vc: version control vc(l) 

get: get a version of an SCCS file get(l) 

sccsdiff: compare tv^o versions of an SCCS file sccsdiff(l) 

formatted output of/ vprintf, vfprintf, vsprintf: print vprintf(3S) 

get client's data passed via the listener, nlsgetcall: nlsgetcall(3N) 

file system: format of system volume, fs: fs(4) 

print formatted output of a/ vprintf, vfprintf, vsprintf: vprintf(3S) 

output of/ vprintf, vfprintf, vsprintf: print formatted vprintf(3S) 

or terminate, wait: wait for child process to stop wait(2) 

to stop or terminate, wait: wait for child process wait(2) 

ftw: walk a file tree ftw(3C) 

what: identify SCCS files what(l) 

signal, signal: specify what to do upon receipt of a signal(2) 

library, libwindows: windowing terminal function libwindows(3X) 

jagent: host control of windowing terminal jagent(5) 

/protocol used between host and windowing terminal under layers(5) 

chdir: change working directory chdir(2) 

get path name of current working directory, getcwd: getcwd(3C) 

write: write on a file write(2) 

putpwent: write password file entry putpwent(3C) 

write: write on a file write(2) 

open: open for reading or writing open(2) 

utmp, wtmp: utmp and wtmp entry formats utmp(4) 

formats, uhnp, wtmp: utmp and wtmp entry utmp(4) 

x286emul: emulate XENIX 80286 x286emul(l) 

x286emul: emulate XENIX 80286 x286emul(l) 

display selected parts of a XENIX object file, hdr: hdr(l) 

channels protocol used by xt(7) driver, /multiplexed xtproto(5) 

protocol used by xt(7)/ xtproto: multiplexed channels xtproto(5) 

bessel: jO, jl, jn, yO, yl, yn: Bessel functions bessel(3M) 

bessel: jO, jl, jn, yO, yl, yn: Bessel functions bessel(3M) 

compiler-compiler, yacc: yet another yacc(l) 

bessel: jO, jl, jn, yO, yl, yn: Bessel functions bessel(3M) 

set default system time zone, timezone: timezone(4) 
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